





MVS/Extended Architecture 
VSAM Catalog Administration: 
Access Method Services 
Reference 


Ol col-Tam nv lelanlel=19 Data Facility Product 
GC26-4136-3 665-XA2 








Mlesiaisce 
macelelectan 


Version 2 
Release 3.0 

















: 
i 
i 
I 
| 
E 
i 
| 
\ 
b 
‘ 
i 
{ 
i 
: 
if 
fd 
l 
he 
£ 
q 
i 
| 
} 
k 
t 
4 
i 
{ 
\ 
t 
i 
\ 
r 
L 
b 
n 


MVS/Extended Architecture 
_VSAM Catalog Administration: 


Access Method Services 
Reference 


<«ff 


Licensed 
Program 





Order Number. Data Facility Product 
GC26-4136-3 


Version 2 
5665-XA2 Release 3.0 











Fourth Edition (December 1987) 
This is a major revision of, and makes obsolete, GC26-4136-2. 


This edition applies to Version 2 Release 3.0 of MVS/Extended 
Architecture Data Facility Product, Licensed Program 5665-XA2, 
and to any subsequent releases until otherwise indicated in new 
editions or technical newsletters. 


The changes for this edition are summarized under "Summary of 
Changes" following the preface. Specific changes are indicated 
by a vertical bar to the left of the change. These bars will be 
deleted at any subsequent republication of the page affected. 
meagan changes that have no technical significance are not 
note 


Changes are made periodically to this publication; before using 
this publication in connection with the operation of IBM 


systems, consult the latest M System/370, 30x 300, a 
Processors Bibliography, GC20-0001, for the editions that are 


applicable and current. 


References in this publication to IBM products, programs, or 
services do not imply that IBM intends to make these available 


in all countries in which IBM operates. Any reference to an IBM 
licensed program in this publication is not intended to state or 


imply that only IBM's program may be used. Any functionally 
equivalent program may be used instead. : 


Requests for IBM publications should be made to your IBM 
representative or to the IBM branch office serving your 
locality. If you request publications from the address given 
below, your order will be delayed because publications are not 
stocked there. 


A Reader's Comment Form is provided at the back of this 
publication. If the form has been removed, comments may be 
addressed to IBM Corporation, P.0. Box 50020, Programming 
Publishing, P.O. Box 49023, San Jose, California, A. 
95161-9023. IBM may use or distribute whatever information you 
supply in any way it believes appropriate without incurring any 
obligation to you. 


© Copyright PRLOP eet nas: Business Machines Corporation 1983, 
1986, 1987 

















eo 
CJ 


te 


“— 





This publication is intended for catalog administrators and VSAM 
system programmers. It contains reference information about the 
access method services commands used to manipulate VSAM catalogs 
and VSAM data sets. 


This book gives the format, a brief description, and examples of 
each access method services command used with VSAM catalogs and 
the objects cava see in them. This book is meant to be a 
companion to 


Guide, GC26- Gist, _and MS7Ectonded Architecture cetelea 


» GC26-4138. 


For information on the use of commands related to VSAM catalog 
format and structure, see Catalog Administration Guide. For 
information on the use of commands | related to VSAM data set 
format and structure, see : 


® Chapter 1, "Guide to Access Method Services" on page l, 
summarizes the access method services functions and the 
commands used to perform them. 


@ Chapter 2, "Introduction" on page 3, provides an overview of 
access method services, including command syntax 
considerations, dynamic allocation, and JCL for data set and 
volume identification, and the use of the time sharing 
option (TSO) and the IBM 3850 Mass Storage System with VSAM 
and access method services. Everyone who intends to use 
access method services should first read this chapter. 


® Chapter 3, "Controlling Command Execution™ on page 2l, 
describes the use of the IF-THEN-ELSE, SET, and PARM 
commands to control command execution and to specify 
diagnostic aids and printed-output options. 


© Chapter 4, "Functional Command Format" on page 29, lists the 
access method services commands and their format, describes 
the required and optional parameters, and lists their 
abbreviations. Examples at the end of each command section 
show how the commands and their parameters are used. 


° Appendix A, "Interpreting LISTCAT Output Listings,™ shows . | 
the output keywords and the field names associated with each 
type of catalog entry, and supplies listings for LISTCAT and 
their interpretation. 


e Appendix B, "Interpreting LISTCRA Output Listings,™ shows 
the information necessary to interpret the listings for a 
recoverable catalog. 


e Appendix C, “Sample Output from CHKLIST,™ shows sa format 
and gives an explanation of the output for CHKEIST 


e Appendix D, "Caution for JCL DD Parameters," gives a list of 
some JCL DD parameters to be used with caution. 


° Appendix E, "Invoking Access Method Services from a Problem 
Program," gives an example of how to use the access method 
services commands in a user program. 


e Appendix F, "Command Reference Summary,™ shows the format of 
each access method services command, and its parameters, 
abbreviations, and defaults. The commands are grouped 
together to allow you to remove these pages and use them as 
a quick-reference guide. 
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e "Glossary" defines terms relevant to access method services, 
VSAM, VSAM data sets, and VSAM catalogs. yas, 
RERE Ss OWLEDG 


Readers of this book are presumed to have a background in 
programming, including: 


@ Job control language 
e VSAM data administration 


@ Catalog administration 


REQUIRED ONS 


You should be familiar with the information presented in the : 
following publications: 


e MVS/ZExtended Architecture Catalog Administration Guide, 
GC26-4138, describes the administration of tasks for 
catalogs and how to use the access method services commands 
to manipulate catalogs, and the objects cataloged in them. 


e MVS7Extended Architecture JCL User's Guide, GC28-135l, 
e MVS/Extended Architecture JCL Reference, GC28-1352, 


describes the JCL parameters referred to in this 


publication. 
e MVS7Extended Architecture Message [Libr : ste ess 

(Volumes 1 and 2), GC28-1376 and GC28-1377, provides a 

complete listing of the messages issued by access method 

SCPViCCS 6 " 
° VS/Extend itecture Da tilities, 


is 
GC26-4150, describes the utility programs available for use 
with non-VSAM data sets. 


e WWSZ end Architecture VSAM Administration: Macro 
Instruction Reference, GC26-4152, provides information on 
macro instructions used to process VSAM data sets. 


@ MVSZExtended Architecture VSAM Administration Guide, 
GC26-4151, provides information on creating and processing 
VSAM data sets, backup and recovery, and various options 
affecting performance. 


CATIONS 


sore the text, references are made to the publications listed 
elow: 


Short Title Publication Title Order Number 


Access Method MVS/Extended Architecture LY26-3953 
Services Logic Access Method Services and 
; Logic LY26-3997 


Cache Device MVSZExtended Architecture GC26-4137 
Administration che vi dministrati 


Catalog j GC26-4138 
Administration Lni j 
Guide 
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Short Title 


Diagnosis Guide | 


Publication Title 


S7 ended chite 
ata Facili roduct 
Version 3: Diagnosis Guide 


MVS7Extended Architecture 


oint/Resta User's 


Order Number 
LY27-9550 



















Checkpoint/ 
Restart User's 
Guide 


Data 
Administration 
Guide 


GC26-4139 



















MVS/Extended Architecture GC26-4140 


a Admini tion Guid 






Introduction to GA32-0028 


the IBM 3850 
Mass Storage 
System 


JCL User's VS/Extended Archi t GC28-1351 

Guide CL User's Guide 

JCL Reference MVSZExtended Architecture GC28-1352 
JCL Reference 


GC35-0017 





OS/VS Mass OS/VS Mass Storage System 
Storage System (MSS) Services: Reference 
Services: Information | 
Reference 

Information 


SC28-0733 


RACF Command Resource Access Control 
Language acilit RACE) Command 
Reference Lanqua Referenc 


RACF General Resource Access Control GC28-0722 


Information Facility CRACF): Genera 


Manual Information Manual 


System-Data S7 ende rchitectu GC26-4149 
Administration System-Data Administration 


MVSZExtended Architecture GC26-4148 
Installation: System 
Generation 


VSAExt e chitecture 
System Programming Library: 
System Macros and 
Facilities 


eS» 
Volumes 1 and 2 


MVSZExtended Architecture 


Message Library: System 


Messages, 
and 2 


Volumes ] 


VS/Extended Architectu 
[SO Command Language 
Reference COS/VS2 TSO 
Command Language Reference, 
as updated by Supplement 
$D23-0259 for MVS/XA) 


VS/Extended Architectu 

[SO Terminal User's Guide 
Cas updated by Supplement 
$D23-0263 for TSO/E) 





















System 
Generation 





GC28-1150 
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GC28-1151 
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and Facilities 



















GC28-1376 
an 
GC28-1377 


GC28-0646 
GC28-1274 






System Messages 











TSO Command | 
Language 
Reference 


























TSO Terminal 
User's Guide 
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Short Title Publication Title Order Number 


Utilities 








GC26-4150 













VSAM GC26-4151 
Administration | 
Guide 








VSAM GC26-4152 
Administration: 

Macro 

Instruction 

Reference 


uniform system of notation describes the format of access 
thod services commands. This notation is not part of the 
nguage; it merely provides a basis for describing the 
ructure of the commands. 


e command format illustrations in this book use the following 
nventions: | 


Brackets [ ] indicate optional parameters. 


Braces { } indicate a choice of entry; unless a default is 
indicated, you must choose one of the entries. 


Items separated by a vertical bar (|) represent alternative 
items. No more than one of the items may be selected. 


An ellipsis ¢(...) indicates that multiple entries of the 
type immediately preceding the ellipsis are allowed. 


Other punctuation Cparentheses, commas, etc.) must be 
entered as shown. 


BOLDFACE type indicates the exact characters to be entered. 
Such items must be entered exactly as illustrated Cin 
uppercase, except in TSO). 


type specifies fields to be supplied 
by the user. 


type indicates a default option. If 
the eee is omitted, the underscored boldface value is 
assumed. 


A * * adn the command format indicates a blank Can empty 
space) must be present before the next parameter. 
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| RELEASE 3.0, JUNE 1987 


| SERVICE CHANGES 


| Minor technical changes have been made. 


S$ -0 986 


NEW PROGRAMMING SUPPORT 
The EXAMINE command allows the user to analyze and report on the 
structural consistency of the index component and/or data 
component of a Key-~sequenced data set CKSDS) cluster. It is 
described in "Chapter 4. Functional Command Format™ and in 
"Appendix F. Command Reference Summary." 
Information has been added to the DEFINE and DELETE commands for 
non-VSAM data sets to reflect the RACF ERASE attribute available 
in RACF Version 1, Release 7. 

SERVICE CHANGES 

( | The first four sections of this manual have been reorganized. 


Minor technical changes have been made. 


$ 0 8 


NEW DEVICE SUPPORT 
Selected examples in DEFINE NON VSAM and IMPORT CONNECT, a 
section of the required parameters for DEFINE PAGESPACE, and the 


Device Type Translate Table shown in Appendix A have been 
updated to reflect 3380 support. 


VERSION 2 PUBLICATIONS 


The Preface includes new order numbers for Version 2. 


Summary of Changes vii 





























Chapter 1. Guide to Access Method Services a ee ee ee ee 

Chapter 2. Introduction e % a> Je i ei. Se era! Se, We tes 

How to Code Access Method Services Commands a Gh, ee ee 
Commands ae ee te 


Positional and Keyword Parameters. 

How to Code Subparameters : 

Alphameric, National, and Special ‘Characters 

How to Continue Commands and Parameters 

The Terminator Scr Gh a ee es as te - S tOr e 

Data Set and Volume Identification gr. te, Oe ee ae! ie es He 

Dynamic allocation Se oe an eee eee : 
JCL DD Statements 


For a VSAM ae Set Bes gr osbiy, Se 156 a: 
For a Volum a ee cae at. Ee 
For a Non- VSAM Data “Set. ete 
For a Snap Dump Bee te oe) ak 4a ee Sk at ee tae 
For a Target Data Set. : SS gs Se, ie -ee, Se ge 


For an Alternate Target Data Se t 
Direct Allocation Using JOBCAT and STEPCAT DD Statements 
Invoking Access Method Services a. oa 
As a Job or Jobstep i ok. Gn was ae oe Ge SES Ge te eee ee te a, GS 
From a TSO Terminal ‘ ee des Be we. ae Me tee a ee ee EY 
From a User's Program : 

Order of Catalog Use ee Ue Me we ee. Bi 
Order of Catalog Search for ALTER a ae oe ee 
Order of Catalog Selection for BLDINDEX Se. te gs 
Catalog Selection for CNVTCAT Ack es 
Order of Catalog Selection for DEFINE % oe oh ce 
Order of Catalog Search for DELETE a ar ae ee 
Order of Catalog Search for LISTCAT i oe ee F 

Mass Storage System (MSS) BW, te oA ea Gat Cab ts et wee Oh. ae Sp 
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Chapter 3. Controlling Command Beeewero a. 6: Se 4s fee SS 
Condition Codes F ee Oe ee ee 
IF-THEN-ELSE Command Sequence 
DO-END Command meee : : 

Null Commands a ee ae 
SET Command a 
PARM Command 5 
Common Continuation Errors in ‘Coding Control Commands 
Control Command Execution Examples 
Control Command Execution with Nested. IF Commands: 
Example 1 
Control Command Execution “with Nested IF Commands: 
Example 2 P ; 
Control Command Execution ‘Using “MAXCC_ Parameter: 
Example 3 
Control Command Execution ‘Using LASTCC Parameter: 
Example 4 ic foe <8, TS 
Control Command Execution “with LASTCC Value. 
Established: Example 5 
Control Command peecuerel Replacing MAXCC Value: 
Example 6 ete, as 6G : ; a ae a ae 


Chapter 4. Functional Command Format a ae ae ee ee 

Functional Command Format Summary nce tes: gp. dle VS! cae, His- cee fe 

ALTER oe dz 
Entry Types” That Can Be Altered : 

ALTER Parameters : Se Gh. Ss ee. See ee A ee 
Required Parameters be Sete Us uk bn, WE ca te Re “Vet oe GG 
Optional Parameters — ‘ ‘ ; 

ALTER Examples 
Alter a Cluster? Ss ‘Attributes: ‘Example 1 
Alter the Entrynames of Generically Named Clusters: 

Example 2 ; 
Alter the Attributes of a Generation Data ‘Group: 
Example 3 oo a ; 
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BLDINDEX : ee BY de a Sa a Se ce 
BLDINDEX Parameters: So des Je al. Rc Gee a es a Oe A 
Required Parameters gy SS ee. 2: eh ee 2 en oe at 
Optional Parameters as ee Vs a ts a 
BLDINDEX Example 
Build an Alternate Index Over a Key-Sequenced Data Set: 
Example 1 oer a ee ee ae a be vor ah ee te Sea tee Ge 
CHKLIST : 
CHKLIST Parameters a a eee 
Required Parameter go sie Ge he, es eS, Sue a Ow, Se OS 
Optional Parameters Bb. wes cee hs he Sie De a A ee cs 
CHKLIST Examples 
Selecting Specific Checkpoint Entries: Examp le 1 
Processing a Member of a Partitioned Chacksoint Data 
Set: Example 2 Bese Sy wee. ee ae ae E.'s 
CNVTCAT SP. et ES oc fat, Se et~ te oes. Det HS AG, ss en a Me, 
CNVTCAT Parameters we. lew. 12d, “ee dE, a Sa Jas. Ga <a. 
Required Parameters 
Optional Parameters 
CNVTCAT Examples : : 
Convert OS CVOL Entries. to Entries in - “VSAM Catalog: 
Example 1 . : 
Convert an OS “CVOL Having Control “Volume Pointer 
Entries: Example 2 ter abe. dit, eee te ye Be BS 
DEFINE ALIAS 
DEFINE ALIAS Parameters ee fe ee ee 
Required Parameters esa od Tes ee ee te, ee. Se ee, “SS 
Optional Parameter 
DEFINE ALIAS Examples 
Define an Alias for a Non-VSAM Data “Set: Example 1 
Define an Alias for a User Catalog: Example 2 : 
DEFINE ALTERNATEINDEX gh cat ae ol. 15s. Ges Sor tes Con “Se 
DEFINE ALTERNATEINDEX Parameters ee ee ae ee 
Required Parameters ea, te 
Optional Parameters 
Data and Index Components of an “Alternate. Index. 3 
DEFINE ALTERNATEINDEX Example ange lat. tee. MR HR RE, <2 
Define an Alternate Index: Example 1 a a ae 
DEFINE CLUSTER ; By, ahs es ce Sw, ae 
DEFINE CLUSTER Parameters. i > es Bb ee Oe. as a he 
Required Parameters Seo sa. Se A tes wa ee, as et ee ge es ce 
Optional Parameters ; 
Data and Index Components of a Cluster 
DEFINE CLUSTER Examples . 
Define a Key-Sequenced Cluster Specifying Data and 
Index Parameters: Example 1 
Define a Key-Sequenced Cluster and an ‘Entry-Sequenced 
Cluster: Example 2 ‘ 
Define a Key-Sequenced Cluster Cin a Unique Data 
Space) in a VSAM Catalog: Example 3 ‘ 
Define a Relative Record Cluster in a Catalog: 
Fxample 4 
Define a Reusable Entry-Sequenced Cluster. in a 
Catalog: Example 5 
Define a Key~Sequenced Cluster in - ‘Catalog: Example 6 
Define an Entry~Sequenced Cluster Using a Model: 
Example 7 see: ues Se hs Gate Se ot SP ove, my 
DEFINE GENERATLIONDATAGROUP ; 
DEFINE GENERATIONDATAGROUP Parameters: 
Required Parameters ar we 
Optional Parameters ‘ 
DEFINE GENERAT LONDATAGROUP Evanple : 
Define a Generation Data Group and a Generation Data 
Set within It: Example 1 je le. 6s Sar, a, ee 8 
DEFINE NONVSAM Bo ak. ss he. ee ah “he ge cis oe ae She, 7 
DEFINE NONVSAM Parameters St Mar. Wee. A Be ts Che “Tae Gas 
Required Parameters Ss vat ah. Sees ee ae te 
Optional Parameters BME. Met fel, Ok Certs we eM cee i cee Ses 
DEFINE NONVSAM Example 
Define a Non-VSAM Data Set: ‘Example L 
DEFINE PAGESPACE : ; ee eS 
DEFINE PAGESPACE Parameters. Se. Weim tie- Wet, SR: Soin Estee coe. ez eee ly stots ae 
Required Parameters gee We cae tis Gs ees ee Bh ode Se 
Optional Parameters ; 
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DEFINE PAGESPACE Examples a ee ae ee ee ee 
Define a NOSWAP Page Space: “Example. 1 ae 
Define a SWAP Page geoee ina eae Example 2 . 38 

DEFINE PATH ‘ go 3 tay te 

DEFINE PATH Parameters wy be es ee ee Ser Se ae. a a 
Required Parameters 7a es ee BS ee. ce a 
Optional Parameters be a Ses wt. ie, te. GB ae Yee a ee OA 

DEFINE PATH Example Be Tes -xae. a ee as 2s cee, SR 
Define a Path: Example 1 Be ne? vee fe. hs ee ame He os 

DEFINE SPACE Ge ae: ee ae a, ee ce Ne SS ee 

DEFINE SPACE Parameters Se she G8. Ss a Rs et. Ae Sv ae 
Required Parameters Be. ae ee ee tee Se, Ae cee ee ee 
Optional Parameters 

DEFINE SPACE ig aa : 

Define a Data Space: Examp le 1 
DEFINE USERCATALOG] HASTERCATALOG ‘ 

DEFINE esol ript i ete eh ce aad Parameters: 
Required Parameters 
Optional Parameters 5. et de a? 

Data and Index Components of Usercatalog oe ee oe 

DEFINE USERCATALOG Examples a a ae 
Defining a VSAM User Catalog, ‘Having Calculated Its 

Space Requirements: Example 1 
Define a User Catalog Beevane Available Suballocatable 
Space: Example 2 o. . 
Define a User Catalog Using the MODEL Parameter: 
Example 3 | P 
Define a VSAM Recoverable_ User Catalog: ‘Example G 
DELETE : : She Gen ok 

DELETE Parameters 
Required Parameters 
Optional Parameters ? 

DELETE Examples We wie te Sig, dace os 
Deleting a Non-VSAM Data Set's Entry: Example 1 ‘ 
Deleting a Key-~Sequenced VSAM Cluster in a Catalog: 

Example 2 a a ee ee a ee a ae ee ee 
Deleting an Entry~Sequenced VSAM Cluster in a VSAM 
Catalog and All Empty Data Spaces On a Volume: 
Example 3 ge EP bs eee Te. Sch. Vek, es dn ee a Rt Sk a UR ee 
Deleting Two Key~Sequenced Clusters in a Catalog: 
Example 4 
Deleting Nonempty. VSAM Data “Spaces on ‘a Volume for a 
YSAM Catalog: Example 5 ne 38 
Deleting a User Catalog: Example 6 
Deleting an Alias Entry ina Catalog: ‘Example 7 
Deleting oo ce ae Named Entries ina Catalog: 
Example 8 Soo. tae tee eee 
List a Generation. Data Group! s Entries, ‘Then Delete 
the Group and Its Data Sets in a Catalog: Example 9 
Deleting a Member of a Partitioned (€Non-VSAM) Data a 
in a Catalog: Example 10 : = se ; 
Deleting a Page apace Example 11 
EXAMINE ; : ae. oaks Je ta 

EXAMINE Parameters eas ts, Se oe es, es Oe 
Required Parameters ee. i te? “Sy GS AA os 
Optional Parameters > 

EXAMINE Examples 
Examine Both Components of a Key-Sequenced Data “Set: 

Example l] 
Examine the Data Component of a VSAM User Catalog: 
Example 2 : 4... : 
EXPORT DISCONNECT ; 

EXPORT DISCONNECT Parameters 
Required Parameters a a ae ae 
Export Disconnect of a User Catalog: Example 1 , 

EXPORT ise oe YE He Se Ee Gat, we. Sa ek eo Ae. OC 

EXPORT. Parameters fa wes ee SR gs oy ree ae SE Ge 
Required Parameters iS up dee AN Sse? We eee SR. eo 
Optional Parameters 

EXPORT Examples : ; 

Exporting a Key~Sequenced ‘Cluster: Example 1 
Exporting an te een arods Cluster: PREP ye: 2 
EXPORTRA ; : a ee ee 
EXPORTRA Parameters S of oe oe oe 
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Required Parameters es lige Sele et. RE cee ede ee. AD be writ el oe 
Optional Parameters ar ai? ae. ai ns cat ee ae se. aE 


EXPORTRA Examples 


Using EXPORTRA for Ali Entries on ‘One- Volume: 
Example 1 


Using EXPORTRA for All Entries on ‘Multiple Volumes: 


Example 2 
Using EXPORTRA for Selected Entries: "Example 3 
IMPORT CONNECT ; je sao ater be ke, es ads ses cB 
IMPORT CONNECT Parameters. S Sw ae te ee OW. Ge a wt ok 
Required Parameters Bo MBE dg bel. Wes “eu Se Se uke Eo pee ts 


Optional Parameters 


Import Connect Example 


Importing to cannes’ a User Catalog: Example r 


IMPORT 
IMPORT Parameters 


Required Parameters nis ves che ads ee i tee Sk. 4 
Optional Parameters 


IMPORT Examples 


Importing a Key-Sequenced Cluster: Example 1 ; 
Importing an aes atta Cluster in a VSAM 
Catalog: Example 2 ‘ ae Cat Se. te cee TS. tas -H. 


IMPORTRA ne ee ee a ee ee ee 
IMPORTRA Parameters ge Se Sa tay Ges ae ee, A 


Required Parameters 
Optional Parameters 


IMPORTRA Example 


Recovering a VSAM Catalog: Example 1—-Part 1 
CEXPORTRA) ; 

Recovering a VSAM Catalog: Example i—Part 2 
CIMPORTRA) : ‘ 


LISTCAT So. tei, Ser ta ee dat We, > eg 
LISTCAT Parameters a eee ee ee ee 


Required Parameters 
Optional Parameters 


LISTCAT Examples : 
Listing a Key-Sequenced “Cluster! Ss ‘Entry in a Catalog: 


Alter a Catalog Entry, 


Example 1 


Example aa 
List Catalog Entries: ‘Example: 3 a 


LISTCRA ; 
LISTCRA Parameters 


Required Parameters 
Optional Parameters 


LISTCRA Example 


PRINT 


Listing a Catalog Recovery Area: Example 1 


PRINT Parameters 


Required Parameters 
Optional Parameters 


PRINT Examples : 


REPRO : 
REPRO Parameters 


Print a Catalog: Example 1 
Print a Catalog: Example 2 


Then List the Modified Entry: 


Print a Key-Sequenced Cluster's Data Records in ‘a 


Catalog: Example 3 
Copy Records from a Non- VSAM Data “Set. into an 


Shs Bah ahaa oe eae Then Print the Records: 


Example 4 
Required Parameters be. tbe aN ee ee 
Optional Parameters Bs. es es ca ome oe. De gy. OR? he 


Cryptographic Parameters a ae ee 
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Decipher Using System Keys: Example 7 

Encipher Using Private Keys: Example 8 ‘ 
Decipher Using Private Keys: Example 9 i tee, 
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User I/70 Routines ee ew ee ee ee we ee ew 


Appendix F. Command Reference Summary ; ae 

ALTER—modify attributes of iad usted defined catalog 
entries 

BLDINDEX—build ‘alternate indexes_ for existing VSAM 
clusters 


| CHKLIST—identify tape volumes mounted when a ‘checkpoint 


was taken 
CNVTCAT—convert OS “CVOL entries into “VSAM catalog entries 
DEFINE ALIAS~——define an alternate name for a user catalog 
or a non-VSAM data set ‘ ; 


DEFINE ALTERNATEINDEX—define a catalog entry for. an 


alternate index , 
DEFINE CLUSTER—define a catalog entry for a VSAM. cluster 
DEFINE GENERATIONDATAGROUP-——create a catalog entry for a 
generation data group. 
weg NONVSAM—define a catalog entry for a non-VSAM data 
se 
DEFINE PAGESPACE—define a catalog entry for a page “space 
DEFINE PATH~—-define a relationship between an alternate 
index and its base cluster ‘ 
DEFINE SPACE--define a VSAM data space in a VSAM catalog 
DEFINE poe eee eee nee coor cn cerane a pes user or 
master catalog & % 
DELETE—~-delete entries from a ‘catalog. , 
EXAMINE-—-Examining Key-Sequenced Data Set ‘Clusters 
EXPORT DISCONNECT——-disconnect a user catalog 
EXPORT——-create a backup or portable copy of a VSAM cluster 
or alternate index ; 
EXPORTRA-~—copy catalog entries from the catalog recovery 
area (CRA) for VSAM recoverable catalogs é 
IMPORT CONNECT—connect a user catalog ; 
IMPORT——-restore a VSAM cluster or alternate index from a 
portable data set created by the EXPORT command 
IMPORTRA-——-restore catalog entries from a portable data set 
created by the EXPORTRA command for ve Bellas 
catalogs d 
LISTCAT—Llist entries. from a catalog ; ; 
LISTCRA—~—-list the contents of the catalog recovery area 
€CRA) for VSAM recoverable catalogs o, -ty eo 
PRINT—print the contents of a data set in 7% 
REPRO—copy data sets, copy integrated catalog facility 
RESETCAT—synchronize a VSAM recoverable catalog to the 
level of its owned volumes a 
VERIFY—-restore a VSAM cluster’ Ss end- of- “file values. 
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Alter 
Attach 


Backup 


Build 


Catalog 


Connect 


Convert 


Copy 


Define 


Figure 1 (Part 1 of 2). 





Figure 1 is a list of tasks that access method services commands 


can be used to perform. 
might want to perform. 
tasks. 
perform each task. 


Description 


attributes in catalog entries 


user catalog to the master catalog 


VSAM catalog 
VSAM data set 
non-VSAM data set 


alternate index 


VSAM data set 
VSAM data set with alternate 
index 


non-VSAM data set 
generation data group 


user catalog to a master catalog 
or another user catalog 
OS CVOL to a master catalog 


non-VSAM data set to VSAM format 
VSAM data set to SAM format 
OS CVOL entries to VSAM 

catalog entries 


data set or catalog 


VSAM catalog 

alias for a non-VSAM data set 
alias for a user catalog 
alias for a VSAM data set 
alternate index 


relationship between an alternate 


index and its base cluster 

generation data group 

page space 

swap data set 

VSAM data set 

VSAM data space 

catalog entry for a non-VSAM 
data set 


Tasks and Commands 


The left column shows tasks that you 
The middle column further describes the 
The right column shows the commands that can be used to 


Command 
ALTER 
IMPORT CONNECT 


REPRO 
EXPORT or REPRO 
REPRO 


DEFINE ALTERNATEINDEX and 
BLDINDEX 


DEFINE CLUSTER 
DEFINE CLUSTER and 
ALTERNATEINDEX 


DEFINE NONVSAM 
DEFINE GENERATIONDATAGROUP 


IMPORT CONNECT 
DEFINE NONVSAM 


REPRO 
REPRO 


CNVTCAT 
REPRO 


DEFINE USERCATALOG 

DEFINE ALIAS 

DEFINE ALIAS 

DEFINE PATH 

DEFINE ALTERNATEINDEX and 
BLDINDEX 


DEFINE PATH 

DEFINE GENERATIONDATAGROUP 
DEFINE PAGESPACE 

DEFINE PAGESPACE 

DEFINE CLUSTER 

DEFINE SPACE 


DEFINE NONVSAM 
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Figure 1 (Part 2 of 2). 
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Description 


user catalog 

alias 

VSAM data spaces and data sets 
alternate index and its paths 
path 

any type of catalog entry 
VSAM data set 

VSAM data space 

generation data group 
non-VSAM data set 

Page space 


user catalog 


user catalog 
VSAM data set 


user catalog 
VSAM data set 


a key~sequenced data set (KSDS) 
cluster 


password 

data set's contents 

catalog's contents 

contents of a catalog or of a catalog 
entry (€formatted) 

contents of a catalog recovery area 

tapes mounted at a checkpoint 


records into a data set 
alternate index 


catalog to another system 


VSAM data set to another system 
non-VSAM data set to another system 


data set 


from a processing-program failure 
from a catalog failure 


data set 

data set's end-of-file information 
catalog entry and/or the contents 
of its object 

data set from a portable copy 

data set 

data set or catalog 


VSAM data set's end-of-file 
indicators 


Tasks and Commands 








Command 


DELETE USERCATALOG 
DELETE ALIAS 

ALTER REMOVEVOLUMES 
DELETE ALTERNATEINDEX 
DELETE PATH 

DELETE | 

DELETE CLUSTER 

DELETE SPACE 

DELETE GENERATIONDATAGROUP 
DELETE NONVSAM 

DELETE PAGESPACE 


EXPORT DISCONNECT 


EXPORT DISCONNECT 
EXPORT or EXPORTRA 


IMPORT CONNECT 
IMPORT or IMPORTRA 


EXAMINE 


LISTCAT 
PRINT 
PRINT 


LISTCAT 
LISTCRA 
CHKLIST 


REPRO 
BLDINDEX 


EXPORT DISCONNECT and 
IMPORT CONNECT 

EXPORT/ IMPORT 

REPRO 


PRINT 

VERIFY 
LISTCRA 
EXPORTRA 
IMPORTRA and 
RESETCAT 

ALTER 

VERIFY 
EXPORTRA/IMPORTRA or 
RESETCAT 
IMPORT 

DELETE 


REPRO 


VERIFY 
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Access method services iS a Service program used with the 
virtual storage access method (VSAM) to establish and maintain 
catalogs and data sets. If you plan to use VSAM, or if you are . 
responsible for maintaining the system catalog, you must use 
access method services commands. 


There are two types of access method services commands: 
functional commands that are used to request the actual work 
(for example, defining a data ‘set or listing a catalog) and 
modal commands that allow the conditional execution of 
functional commands. The access method services modal commands 
are presented under Chapter 3, "Controlling Command Execution"™ 
on page 21. The access method services functional commands and 
their parameters are listed in alphabetic order under 

Chapter 4, "Functional Command Format™ on page 29. Examples of 
the use of each command are included. TSO users are allowed to 
use only the functional commands. 


This is a reference book only. See 
and VSAM Administration Guide for information on the tasks 
performed using access method services commands. 





All access method services commands have this general structure: 


COMMAND parameters ... [terminator] 


Commands 


COMMAND specifies the type of service requested. The parameters 
further describe the service requested. The terminator 
indicates the end of the command statement. 


Commands can begin at or to the right of the left margin. For 
batch processing jobs, the default margins are 2 and 72. 


Commands are separated from their parameters by one or more 
separators (blanks, commas, or comments). For some parameters, 
parentheses are specified as separators. Comments are strings 
of characters surrounded by a /® and an ¥/. Comments may 
contain any characters except an 'X/'., 


Many of the commands and keyword parameters may be abbreviated. 
The abbreviations allowed are listed in the description of each 
command and in Appendix F, "Command Reference Summary™ on 

page 326. Keyword parameters in plural form may also be coded 

in the singular form. Restrictions that apply to abbreviations 
under TSO are described under "From a TSO Terminal" on page 13. 


Positional and Keyword Parameters 
A parameter may either be a positional parameter or a keyword 
parameter. Positional parameters must always appear first ina 


parameter set. In access method services, positional parameters 
are never optional. 
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For example, in: 


DELETE - a 
USERCAT - ed 


USERCAT is a positional parameter that specifies the entryname 
to be deleted. 


A Keyword parameter is a specific character string, which may 
have a value following it. For example, in: 


VOLUME (25DATA) 


VOLUME is a keyword that indicates that the value 25DATA is a 
volume serial number. 


A keyword parameter may have a set of subparameters. 
Subparameters follow the same rules as parameter sets in 
general. When the subparameters are positional, the first 
subparameter is always required. 


Positional parameters and subparameters sometimes consist of 
lists of items. Unless the list contains only one item, it must 
be enclosed in parentheses, which may be preceded and followed 
by blanks, commas, or comments. For example: 


DELETE(entryname [...1) 


indicates that, if more than one entry is to be deleted, the 
list of entrynames must be enclosed in parentheses. However, if 
ee entryname is specified, the parentheses are not 
required. 


An item ina list can be a parameter set itself. Each such 
item, as well as the list of items, is enclosed in parentheses. 


Given: —_, 
OBJECTS( (entryname NEWNAME (newname))...) cod 
the following are valid: 
OBJECTSC - 
ENTRY] NEWNAMECNEWNAME] ) > 
OBJECTSC - 


CENTRYL NEWNAMECNEWNAME1)) - 
CENTRY2 NEWNAMECNEWNAME2) >) 


In the first case, only one entry is to be renamed. The 
entryname and its new name are enclosed in parentheses. 


In the second case, each entryname and its new name are enclosed 
in parentheses and the entire list is enclosed in parentheses. 


All parameters and subparameters must be separated from each 
other by one or more separators (commas, blanks, or comments). 
There is one exception: Parameters that immediately follow a 
subparameter set that is enclosed in parentheses do not need to 
be separated from the closing parenthesis. 


A value cannot contain commas, semicolons, blanks, parentheses, 
or slashes unless the entire value is enclosed in single 
quotation marks. A single quotation mark ina field enclosed in 
sell ee quotation marks must be coded as two single quotation 
marks. 


The values you specify in the parameters can be surrounded by 

separators. Some values can be longer than a single record. 

When a value is longer than a single record, you indicate that | 

it is continued by coding a plus sign (+) followed only by a 

blanks or a comment. The first nonseparator character found in ‘ Y 

Boe following the plus sign is treated as a continuation of oo 
e value. 
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In some parameters it is necessary to specify a password 
following the name of a catalog entry or the name of a JCL DD 
statement. You do this by coding the name, a slash, and the 
password. (Separators are allowed on either side of the slash.) 
For example: 


DELETE PAYROLL/CTLGPAY 
specifies the password CTLGPAY for the data set PAYROLL. 


When you specify a password following a name, you must remember 
the convention for entering commands. If you code: 


MYNAME/ XWORDX/ 


MYNAME is treated as a name followed by the comment WORD. If 
you want XNORDX/ to be the password, you code either: 


MYNAMEZ * XWORDxX-~ * 
or 
MYNAME/ XWORDX/ 


Notice that the second example contains a blank after the first 
slash that separates the name from the password. 


How to Code Subparameters 


The following coding conventions apply to the subparameters 
listed in this section: 


e When the subparameter contains a special character, enclose 
it in single quotation marks; for example, CODEC'XSECRETX'). 


e When the subparameter contains a special character and a 
single quotation mark, code the embedded quotation mark as 
two single quotation marks; for example, VOLUMES(C’one'’'&"). 


e When you code the subparameter in hexadecimal form, two 
hexadecimal characters represent one alphameric or special 
character. Because the character string will be right 
justified, you should use an even number of hexadecimal 
characters; for example, MASTERPWCX'E3D6D7') is the same as 
MASTERPWCTOP). 


e When the subparameter contains a lowercase alphabetic 
est lhek oalig it will be folded to an uppercase alphabetic 
character. 


The subparameters most often referred to in this book are: 


can contain 1 to 44 alphameric or national characters, and 
two special characters (the hyphen (-) and the 12-0 
overpunch (X'CO0')). 


Names that contain more than 8 characters must be segmented 
by periods; 1 to 8 characters may be specified between 
periods. 


The first character of any name or name segment must be 
either an alphabetic character or a national character. 


code 


can contain 1 to 8 alphameric or special characters. 


can contain 1 to 44 alphameric or national characters, and 
two special characters (the hyphen (€-) and the 12-0 
overpunch (X'C0')). 
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Names that contain more than 8 characters must be segmented 
by periods; 1 to 8 characters may be specified between 
periods. A name that is segmented by periods is called a 
qualified name. Each name segment is referred to as a 
qualifier. : 


The first character of any name or name segment must be 
either an alphabetic character or a national character. 


For a partitioned data set, entryname must be specified in 
the format: pdsnameC€Cmembername). Blank characters are not 
allowed between the left and right parentheses enclosing 
the membername, or between pdsname and the left 
parentheses. 


If you specify an entryname in the format 
entryname(modifier), and the entryname is not the name of a 
partitioned data set, only that portion of the name 
preceding the left parenthesis will be used. The modifier 
enclosed in parentheses will be ignored. , 


a 
can contain 1 to 8 alphameric or national characters, and 


two special characters Cthe hyphen (-) and the 12-0 
overpunch CX*CO0')). 


The first character of any name or name segment must be 
either an alphabetic character or a national character. 


newname 
can contain 1 to 44 alphameric or national characters, and 
two special characters (the hyphen (-) and the 12-0 
overpunch (X'C0")). | 
Names that contain more than 8 characters must be segmented 
by periods; 1 to 8 characters may be specified between 
periods. 
The first character of any name or name segment must be 
either an alphabetic character or a national character. 
can contain 1 to 8 EBCDIC characters. 


can contain 1 to 8 alphameric or special characters. 

) 
specifies the entryname for a partitioned data set. Blank 
characters are not allowed between the left and right 


parentheses enclosing the membername, or between pdsname 
and the left parenthesis. 


can contain 1 to 255 EBCDIC characters. 


a volume serial number, can contain 1] to 6 alphameric, 
national, or special characters. 
Alphameric, National, and Special Characters 


The following is a list of alphameric, national, and special 
characters that are referred to throughout this book: 


® Alphameric characters: 
alphabetic characters A-Z 


numeric characters 0-9 
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° National characters 
( at sign [a] 
= dollar sign [$] 
pound sign [#] 
° Special characters 
ampersand [&] 
asterisk [x] 
blank [ J] 
braces [{ or }] 
brackets [[f or ]] 
comma [,] 
equal sign [=] 
hyphen [-] 
parenthesis [(€ or )] 
period [.] 
plus sign [+] 
semicolon [;] 
Single quotation mark ['] 


( slash [7] 


How to Continue Commands and Parameters 


Commands can be continued on several records or lines. Except 
for the last line, each record or line must have a hyphen or a 
plus sign as the last nonblank character before or at the right 
margin. 


A hyphen indicates continuation of the command. A plus sign 
indicates continuation of the command and continuation of a 
value within the command. 


These two types of continuation are shown in the example below: 
DELETE - 


CENTRY1 - 
ENTRY2 - 


NONVSAM 
A blank record or a record ending with a complete comment must 
end with a continuation mark when it appears in the middle of a 
command and when it precedes or follows the THEN and ELSE 
clauses of an IF command. 


° IF LASTCC = 0 - 
THEN - 


REPRO ... 
“XCOMMENT WITH NO CONTINUATION MARK AFTERX/ 





Because no continuation mark (hyphen) follows the comments, a 
null command is assumed. The ELSE keyword will not match up 
with the THEN keyword. 
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The Terminator 








Records ending with partial comments must always end with a 
continuation mark. Also, remember that only blank characters 
may specs between a continuation mark and the end of the 
recor 


Note: The DO-END sequence does not require continuation 
characters. If continuation characters are used, they may be 
taken as a null command or cause unpredictable results. 


The terminator indicates the end of the command. The terminator 
can be either a semicolon or the absence of a continuation mark. 


If you use the semicolon as the terminator, it cannot be 
enclosed in quotation marks or embedded in a comment. 
Everything to the right of the semicolon is ignored. 


If there is information to the right of the semicolon that is 
continued to another record, all the information, including the 
continued information, is ignored. 


For example, if you code: 


PARM TEST CTRACE); PARM — 
GRAPHICS (CCHAINCTN)D)D/XCOMMENTX/ - 
PRINT ... 

REPRO 


Characters following the semicolon terminator are ignored. 
Because there is a continuation mark Chyphen) at the end of the 
second record, the PRINT command is also ignored. The first 
PARM command and the REPRO command are the only commands that 
are recognized. 





DYNAMIC ALLOCATION 


Access method services commands require that both data sets and 
volumes be identified when they are used. A data set must be 
identified when it is accessed. A volume or volumes must be 
identified when VSAM accesses the volume table of contents 
(VTOC), allocates or releases space using OS/VS DADSM functions, 
or accesses a catalog recovery area. (See Catalog 

a for information on this option.) 


A VSAM data set or volume can be identified through JCL or by 
the data set name or volume serial number within the command 
that requires the data set or volume for its execution. If JCL 
is not used, an attempt is made to dynamically allocate the data 
set or volume, as required. 


To dynamically allocate a VSAM data set, the data set name must 
exist and be cataloged. The catalog that contains the entry 
must be either a user catalog identified with a JOBCAT or 
STEPCAT DD statement, a user catalog whose name or alias is the 
oie qualifier of the qualified data set name, or the master 
catalog. 


To dynamically allocate a non-VSAM data set, the data set name 
must exist and must be cataloged. The catalog that contains the 
entry must be either a user catalog identified with a JOBCAT or 
STEPCAT DD statement, a user catalog or OS CVOL whose name or 
alias is the first qualifier of the qualified data set name, or 
the master catalog. 


Access method services dynamically allocates VSAM and non-VSAM 
data sets with a disposition of OLD 
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JCL DD STATEMENTS 


For a VSAM Data Set 


For a Volume 








When a user catalog is identified by name in an access method 
services command Cusing the CATALOG parameter) or when VSAM 
determines that a specific user catalog must be accessed, an 
attempt is made to dynamically allocate it, if it has not been 
identified with a JOBCAT or STEPCAT DD statement. 


In order to dynamically allocate a volume, it must already be 
mounted as permanently resident or reserved. The PRIVATE and 
PUBLIC use attributes should be carefully considered when you 
mount a volume. 


JCL should be used for allocation with data sets that reside on 
Mass Storage System (MSS) volumes, because MSS volumes are 
rarely mounted as permanently resident or reserved. A request 
to dynamically allocate a data set on MSS, or an MSS volume, may 
result in a nonzero return code from allocation. 


When a JCL DD statement is used to identify a data set, the 
following information must be included on the DD statement. 


e The data set name. 


e The unit and volume serial number(s), if the data set is not 
cataloged. 


e The disposition. 


® For VSAM data sets, the AMP="AMORG* parameter is required if 
the JCL also supplies unit and volume serial number 
information. 


The two DD statements shown below demonstrate two different 
methods by which you can describe and allocate a VSAM data set: 


//NSAMDS1 DD DSN=VSAM.DATA.SET1, DISP=OLD 
//NSAMDS2 DD DSN=VSAM.DATA.SET2,VOL=SER=VSEROL, 
// UNIT=DISK, DISP=OLD, AMP="AMORG' 


Access method services does not provide specific protection for 
data sets ina shared environment. Therefore, you should 
specify DISP=OLD on the DD statement for any data set that could 
be accessed improperly in a shared environment. 


VSAM uses default buffering for VSAM data sets. The default is 
the buffer space value contained in the data set's catalog 
entry. You may want to override this tire erica BUFSP 


subparameter of the AMP parameter (see 
for information on this parameter). 


To identify and allocate a volume, the following information 
must be included: : 


e The volume serial number 
e The disposition 
e The unit 


For example, the DD statement shown below identifies and 
allocates volume VSEROI: 


//NOLDD DD VOL=SER=VSERO1,UNIT=DISK, DISP=OLD 


Concatenated DD statements are supported under circumstances 
explicitly specified in the remainder of this publication. 
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For a Non-VSAM Data 


For a Snap Dump 





"Direct Allocation Using JOBCAT and STEPCAT DD Statements" on 
page ll contains a description of the DD statements required for 
user catalogs. 


Set 


Methods of describing and allocating non-VSAM data sets are 
shown in the DD statements of the examples provided with the 
following commands: BLDINDEX, EXPORT, IMPORT, REPRO, 
PRINT,EXPORTRA, and IMPORTRA. 7 


If access method services encounters a condition that requires 
it to abort a job, it takes a snap dump of virtual storage. An 
eda DD statement is required to obtain the snap dump; for 
example, 


//AMSDUMP DD SYSOUT=A 
If you do not supply an AMSDUMP DD statement and access method 


services encounters a condition requiring the job to be aborted, 
it produces only an abbreviated dump. 


For a Target Data Set 


The normal target data set for listing is SYSPRINT. The default 
parameters of this data set are: 


® Record format: VBA 
® Logical record length: 125, that is, 121+4 
© Block size: 629, that is, €5x€1214+4))+64 


Print lines are 121 bytes in length. The first byte is the ANSI 
CAmerican National Standards Institute) control character. The 
minimum specifiable LRECL is 121 (€U-format records only). Ifa 
smaller size is specified, it is overridden to 121. 


It is possible to alter the above defaults through specification 
of the desired values in the DCB parameter of the SYSPRINT 
statement. The record format, however, cannot be specified as F 
or FB. If you do specify either one, it is changed to VBA. 


For an Alternate Target Data Set 


In several commands you have the option of specifying an 
alternate target data set for listing. If you do specify an 
alternate, you must specify DCB parameters in the referenced DD 
statement by using the attributes described above. 


When specifying an alternate target data set, you should not 
specify F or FB record formats. 


Note: JCL statements, system messages, and job statistics are 
written to the SYSPRINT output device, not to the alternate 
target data set. Appendix B, "Interpreting LISTCRA Output 
Listings™ on page 301 shows an example of the use of an 
alternate target data set. 
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DIRECT ALLOCATION USING JOBCAT AND STEPCAT DD STATEMENTS 


User catalogs can be allocated directly by using a JOBCAT or 
STEPCAT DD statement. 


You can specify a catalog that is to be available for use only 
with a job step, or that is to be available for the entire job. 
A STEPCAT DD statement identifies a catalog that is available 
for a single job step; a JOBCAT DD statement identifies a 
catalog that is available during the entire job. When both 
JOBCAT and STEPCAT catalogs are specified, the user catalog 
specified by STEPCAT is used for the job step. The JOBCAT and 
STEPCAT statements you code should be in the form: 


//JOBCAT DD DISP={OLD| SHR}, 
4/4 


DSNAME=usercatname 
and 
S/STEPCAT DD DISP={OLD|SHR}, 
// DSNAME=usercatname 


Because the master catalog contains information about each user 
catalog, you do not need to specify the catalog's volume and 
device information. 


You can specify more than one user catalog for a job or job 
step. To indicate another user catalog, follow the JOBCAT or 
STEPCAT DD statement with a concatenated DD statement—an 
pitas DD statement that specifies the name of another user 
catalog: 


//STEPCAT DD DISP=SHR, DSN=MGMTCATI 
// DD DISP=SHR, DSN=MGMTCAT2 


Supplying a JOBCAT or STEPCAT DD statement to allocate the 


‘catalog is optional when: 


e Your job processes a user catalog (that is, when your. 
sequence of access method services commands adds, modifies, 
lists, or deletes a catalog entry) 


e Your job includes a space allocation request directed toward 
a volume that contains VSAM data spaces (that is, a DEFINE 
SPACE or DELETE SPACE command) 


® Your job causes a VSAM data set to be opened and that data 
set is defined ina user catalog (that is, a REPRO or PRINT 
of a VSAM data set, a DELETE with the ERASE option, EXPORT, 
IMPORT, IMPORTRA, BLDINDEX, or VERIFY) 


For information on REPRO and JOBCAT/STEPCAT DD statements, 
see Catalog Administration Guide. — 


Supplying a JOBCAT or STEPCAT DD statement to allocate the 
catalog 1s required when: 


e Your job causes the catalog to be opened as a data set (for 
example, using the PRINT command to print a catalog, using 
the LISTCRA command with the COMPARE option, or using the 
Hare <chmene to restore end-of-file indicators of a user 
catalog). | 


e Your job causes the scheduler allocation of the user catalog 
to be bypassed because unit and volume information was 
specified on the DD statement describing the VSAM data set 
defined in that user catalog. 


Chapter 2. Introduction lL] 














INVOKING ACCESS METHOD SERVICES 


AS A JOB OR JOBSTEP 


When you want to use an access method services function, you | 
issue a command and specify its parameters. Your request is Y 
decoded, one command at a time, and the appropriate functional * 
routines are then called to perform all services required by 

that command. 


There are three ways you can invoke the access method services 
program: 


e As a job or jobstep 
e From a TSO terminal 
e From within your own program 


You can execute the IDCAMS program and include the command and 
its parameters as input to the program. You can also call the 
IDCAMS program from within another program and pass the command 
and its parameters to the IDCAMS program. 


Time sharing option (TSO) users can execute access method 
services functional commands from the TSO terminal as though 
they were TSO commands. (See Appendix E, "Invoking Access 
Method Services from a Problem Program™ on page 319, for 
information on invoking access method services. ) 


For more details on the structure and operation of access method 
services, see oO ; 


You can use job control language (JCL) statements to invoke 
access method services. The examples that illustrate each 
command's use invoke access method services with JCL statements. 
You identify the access method services program with PGM=IDCAMS. 


//NOURJOB JOB YOUR INSTALLATION'S JOB=ACCOUNTING DATA 
4/7 JOBCAT DD DSNAME=YOUR.CATALOG, DISP=SHR 

//STEPI EXEC PGM=IDCAMS 

//STEPCAT DD DSNAME=ANOTHER.CATALOG, DISP=SHR 
//SYSPRINT DD SYSOUT=A 

J/SYSIN DD XxX 


Caccess method services commands and their parameters) 


7% 


e //YOQURJOB is required. The JOB statement describes your job 
to the system. Your installation might require you to 
supply user identification, accounting, and authorization 
information with the JOB statement's parameters. 


e //JOBCAT is optional. The JOBCAT DD statement identifies a 
user catalog that can be used by each of the job's steps. 
Because the master catalog is always open and available to 
all jobs on the system, you should not identify it with a 
JOBCAT DD statement. 


® //STEP1 is required (that is, an EXEC statement is 
required). The EXEC statement invokes access method 
services to decode and process the input statements (that 
is, the access method services commands and parameters 
contained in the SYSIN data set). You can use the PARM 
operand of the EXEC statement to pass parameters to access 
method services. See the description of the PARM command in 
Chapter 3, "Controlling Command Execution" on page 21, for 
an explanation of the options you can specify. 


e //STEPCAT is optional. The STEPCAT DD statement identifies 
a user catalog that can be used when processing the jobstep. 
If user catalogs are identified with JOBCAT and STEPCAT DD 


= 
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statements, only the catalog(s) identified with the STEPCAT 
DD statement and the master catalog are used with the 
jobstep. Because the master catalog is always open and 
available to all jobs on the system, you should not identify 
it with a STEPCAT DD statement. 


@ //SYSPRINT is required. The SYSPRINT DD statement 
identifies the output device Cusually a printer ina batch 
job) to which access method services sends messages and 
output information. (See "For a Target Data Set™ on page 10 
for more details on how to describe an output device other 
than SYSOUT=A.) 


e //SYSIN is required. The SYSIN DD statement identifies the 
source of the input statements. An input statement is a 
functional or modal command and its parameters. When you 
code SYSIN DD *, you identify the immediately following 
statements as input. 


The last input statement may be followed by a delimiter 
statement that has "/X*" in the first two columns. The 
restrictions that apply to all access method services commands 
are ert alls in “How to Code Access Method Services Commands" 
on page 3. 


FROM A TSO TERMINAL 


TSO is a subsystem that provides conversational time sharing 
from remote terminals. You can use TSO with VSAM and access 
method services to: 


® Execute access method services commands 
e Execute a program to call access method services 


When you use TSO to process your data, you can invoke access 
method services from your TSO terminal. Each time you issue an 
access method services command as a TSO command, TSO builds the 
appropriate interface information and invokes access method 
services. 


You can issue one command at a time. Access method services 
processes the command completely before TSO allows you to 
continue processing. Except CHKLIST, all the access method 
services functional commands referred to in this book are 
supported in a TSO environment. 


When TSO is used with access method services, the following 
differences must be observed: 


® TSO allows the initial characters of a Keyword to be 
supplied as an abbreviation of the keyword. The only 
restriction is that enough initial characters must be 
supplied to make the keyword unique. TRACKS, for example, | 
could be abbreviated TR, TRA, or TRAC, because no other 
keyword within the same command can be abbreviated in the 
same way. 


Some abbreviations that are acceptable to access method 
services, such as CYL, CYLINDER, REC, RECORD, cannot be used 
under TSO because the abbreviations do not contain enough 
initial characters to make the keyword unique. TSO cannot 
tell whether you mean CYLINDERS or CYLINDERFAULT when CYL or 
CYLINDER is used. Similarly, abbreviations REC and RECORD 
are ambiguous; TSO does not know if you mean RECORDS or 
RECORDSIZE. 


® In addition, the abbreviations described in the remainder of 
this publication (for example, TRK for TRACKS) are 
acceptable to TSQ. 

e When a parameter's value consists of a list of one or more 
parenthesized parameter sets, the outer parentheses 
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surrounding the list are always required. For example, if 

'-lowkey and highkey form a parameter set that can be repeated 
several times, then the outer parentheses are required even / 
when just one parameter set is specified; as follows: 


KEYWORD( Clowkey highkey) ) 





@ Under TSQ, a volume serial number can consist of alphabetic, 
national, numeric, or special (hyphen only) characters; if 
any other characters are used, the volume serial number 
cannot be used as an entryname under TSO 


e A name can be specified in quotation marks or not in 
quotation marks. Under TSO, however, a prefix (for example, 
the userid) is added to a name that is not in quotation 
marks. The prefix becomes the first qualifier in the name. 
If the name is a volume serial number Cas it may be in the 
DELETE command, for example), enclose it in quotation marks; 
if hte do not, a prefix is added to the volume serial 
number. 


6 Under TS0, a password can be supplied with any entryname; 
the password is ignored if not required. 


Note: At a TSO terminal, the logon password is checked 
first, before the user is prompted to supply a password for 
a cluster. Checking the logon password counts as one 
attempt to obtain a password. If the user has not specified 
ATTEMPTS in the DEFINE command, only one attempt to supply 
the catalog's password is allowed because the default is 
two. 


8 Under TSO, the user is prompted to complete a fully 
qualified name. The user is also prompted to supply 
required, but omitted, parameters. 


e The modal commands, used to control execution CIF-THEN-ELSE / | 
command sequence, DO-END command sequence, SET, and PARM), et 
are not allowed under TS50. mae 


° Under TSO, the SYSPRINT data set is not used. The OUTFILE 
parameter may be used to specify a data set to receive the 
output procedure from access method services. 


For details about the format of a displayed catalog entry 
Cresulting from a LISTCAT command) for a TSO user, see 
Appendix A, "Interpreting LISTCAT Output Listings™ on page 256. 


Other TSO restrictions are noted with the descriptions of each 
appropriate parameter. 


For details about writing and executing programs and allocating 
data sets with TSO, see JS0 Terminal User's Guide and [SQ 


FROM A USER'S PROGRAM 


A processing program can invoke access method services with the 
ATTACH, LINK, LOAD, and CALL macros. Before the program issues 
the invoking macro, however, it must initialize the appropriate 
register and argument list contents. 


The contents of registers follow standard linkage conventions; 
that is, register 1 contains the address of the argument list, 
register 13 contains the address of a save area, register 14 
contains the address of the return point, and register 15 
contains the address of the entry Ean IDCAMS in access method 
services. 


The contents of the argument list are described in af ™ 


Appendix E, "Invoking Access Method Services from a Problem : 
Program™ on page 319. For information on manipulating sensitive 
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data ina secured environment, see "Authorized Program Facility"™ 
in ; 


You can specify the catalog to be searched or selected for an 
entry with the CATALOG parameters, or with a JOBCAT DD or 
STEPCAT DD statement. 


Order of Catalog Search for ALTER 


The order in which catalogs are searched when an entry is to be 
located for ALTER is: 


1 


If a catalog is specified in the CATALOG parameter, only 
that catalog is searched. If the entry is not found, a ™no 
entry found" error is returned to the user. 


Any user catalogs) specified in the current job step with a 
STEPCAT DD statement is searched. If more than one catalog 
1S specified for the job step, the catalogs are searched in 
order of concatenation. If the entry is found, no other 
catalog is searched. 


If a STEPCAT catalog 1s specified and the entry is not 
found, the JOBCAT catalog is not searched. The catalog 
search continues with step 3 below. 


If no STEPCAT catalog is specified for the job step, anda 
user catalog is specified for the current job with a JOBCAT 
DD statement, the JOBCAT catalog(s) is searched. If more 
than one catalog 1s specified for the job, the catalogs are 
searched in order of concatenation. If the entry is found, 
no other catalog is searched. Otherwise, 


If the entry is identified with a qualified entryname, and 
it is not of the generic form, and its first qualifier is 
the same as: 

@ The name of a user catalog, or 

e The alias of a user catalog, or 

e The alias of an OS CVOL, 

the user catalog or OS CVOL so identified is searched. If 
the entry is found, no other catalog is searched. 
Otherwise, 

The master catalog is searched. If the entry is not found 


in any of the indicated catalogs, a "no entry found™ error 
is returned to the user. 


Order of Catalog Selection for BLDINDEX 


The order in which catalogs are selected to contain work file 
entries is: 


1. 


If a catalog is specified with the CATALOG parameter, that 
catalog is selected to contain work file entries. 


Otherwise, the user catalog specified in the current job 
step (CSTEPCAT) or, if none is specified for the job step, 
the user catalog specified for the current job CJOBCAT) is 
selected to contain the work file entries. If more than one 
catalog is specified for the job step or job, the first 
STEPCAT or JOBCAT catalog is selected to contain the work 
file entries. 
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3. Otherwise, if the entries (data set name on the DD | 
statement) are identified with qualified entrynames and the ff 
first qualifier is the same as: ‘ey 





| YO 
¢ The name of a user catalog, or 

6 The alias of a user catalog, | 

the user catalog so identified is selected to contain the 

work file entries. 

G. Otherwise, the master catalog is selected to contain the 
work file entries. 

Catalog Selection for CNVTCAT 

The target catalog selected to receive the converted entries is 

the catalog specified in the OUTFILE, OUTDATASET, or CATALOG 

parameter. 

The source catalog, the catalog that contains the entries to be 

converted, is the catalog specified in the INFILE or INDATASET 

parameter. 

If there are alias entries for OS CVOLs, the master catalog 

always receives alias entries that point to OS CVOLs. 

Order of Catalog Selection for DEFINE 

The order in which catalogs are selected when an entry is 

defined is: 

1. If a catalog is specified in the CATALOG parameter, that 
catalog is selected to contain the entry to be defined. \ 

2. When a non-VSAM generation data group (GDG) data set is So! 

: defined, the catalog containing the GDG base is selected to 
contain the non-VSAM entry still to be defined. Otherwise, 

3. The first user catalog specified in the current job step 
CSTEPCAT) or, if none is specified for the job step, the 
first user catalog in the current job (JOBCAT), is selected 
to contain the entry to be defined. ("Direct Allocation 
Using JOBCAT and STEPCAT DD Statements™ on page 11 describes 
how you can specify a user catalog for the current job step 
or current job.) Otherwise, 

G4. If no user catalog is specified for the current job step or 
job, and the entry's name is a qualified name, and the first 
qualifier (that is, the first one to eight characters before 
the period) is the same as: 
® The name of a user catalog, or 
e The alias of a user catalog, 
the catalog so identified is selected to contain the entry 
to be defined. 

5. If no catalog has been identified, either explicitly or 
implicitly, VSAM defines an object in the master catalog. 
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Order of Catalog Search for DELETE 


If this is not a generic delete, the order in which catalogs are 
searched to locate an entry to be deleted is: 


Ly 


If a catalog is specified in the CATALOG parameter, only 
that catalog is searched. If the entry is not found, a "no 
entry found™ error 15S returned to the user. Otherwise, 


Any user catalog(s) specified in the current job step Cwith 
a STEPCAT DD statement) is searched. If more than one 
catalog is specified for the job step, the catalogs are 
searched in order of concatenation. If the entry is found, 
no other catalog is searched. 


If a STEPCAT catalog is specified and the entry is not 
found, the JOBCAT catalog is not searched. The catalog 
search continues with step 3 below. 


If no STEPCAT catalog is specified for the job step, anda 
user catalog is specified for the current job (with a JOBCAT 
DD statement), the JOBCAT catalog(s) is searched. If more 
than one catalog is specified for the job, the catalogs are 
searched in order of concatenation. If the entry is found, 
no other catalog is searched. Otherwise, 


If the entry is identified with a qualified entryname and 
its first qualifier is the same as: 


e The name of a user catalog, or 

e The alias of a user catalog, or 

6 The alias of an OS CVOL, 

the user catalog or OS CVOL so identified is searched. If 
the entry is found, no other catalog is searched. 
Otherwise, 

If the entry is not found, the master catalog is searched. 


If the entry is not found in the master catalog, a “no entry 
found™ error is returned to the user. 


If this is a generic delete, the order in which catalogs are 
searched to locate all applicable entries to be deleted is: 


Ls 


If a catalog is specified in the CATALOG parameter, only 


that catalog is searched. If an entry that matches the 
supplied qualifiers is not found, a "no entry found" error 
is returned to the user. Otherwise, 


Any user catalog(s) specified in the current job step (with 

a STEPCAT DD statement) is searched. If more than one 
catalog is specified for the job step, the catalogs are 

searched in order of concatenation. The JOBCAT catalog is 
ih searched. The catalog search continues with step 3 
elow. 


If no STEPCAT catalog is specified for the job step, anda 
user catalog is specified for the current job (with a JOBCAT 
DD statement), the JOBCAT catalog(s) is searched. If more 
than one catalog is specified for the job, the catalogs are 
searched in order of concatenation. The catalog search 
continues with step 3 below. 


If the entry is identified with a qualified entryname and 
its first qualifier is the same as: 


e The name of a user catalog, or 
e The alias of a user catalog, or 


6 The alias of an OS CVOL, 


Chapter 2. Introduction 17 














the user catalog or OS CVOL so identified is searched. The 
catalog search continues with step 4 below. Otherwise, 


4. The master catalog is searched. If an entry has not been 
found in any of the catalogs searched that matches the 
Abilgests qualifiers, a "no entry found" error is returned to 

e user. ; | 


CAUTION: If the generic form of entryname is used to delete 
catalog entries, and the catalog is not specified via the 
CATALOG parameter, entries may be deleted from the master 
catalog if they meet the specified qualification. 


Order of Catalog Search for LISTCAT 


When the ENTRIES parameter is not specified, or when the command 
is not executed through TSO and it is not a generic LISTCAT, the 
order in which catalogs are searched when entries are to be 
listed using the LISTCAT command is: 


1. If a catalog is specified in the CATALOG parameter, only 
that catalog is listed. Otherwise, 


2. The first user catalog specified in the current job step 
(STEPCAT) or, if none is specified, the first user catalog 
specified in the current job (CJOBCAT) is listed. Otherwise, 


3. If no user catalog is specified in the current job step or 
job, the master catalog is listed. 


If the command is not a generic LISTCAT and if the ENTRIES or 
LEVEL parameter is specified or when the command is executed 
through TS0, the order in which catalogs are searched when 
entries are to be listed using the LISTCAT command is: 


l. If a catalog is specified in the CATALOG parameter, only 
that catalog is searched. If the entry is not found, a "no 
entry found" error is returned to the user. Otherwise, 


2. Any user catalog(s) specified in the current job step 
CSTEPCAT) or, if none is specified for the job step, any 
user catalog(s) specified for the current job CJOBCAT). If 
more than one catalog is specified for the job step or job, 
the job step or job catalogs are searched in order of 
concatenation. If the entry is found, no other catalog is 
searched. Otherwise, 


3. If the entry is not found, and the entry's name is a 
qualified name, and the first qualifier (Cthat is, the first 
1 to 8 characters before a period) is the same as: 
e The name of a user catalog, or 
e The alias of a user catalog, or 
@ The alias of an OS CVOL, 


that user catalog or OS CVOL is searched. If the entry is 
found, no other catalog is searched. Otherwise, 


G. The master catalog is searched. If the entry is not found, 
a "no entry found™ error is returned to the user. 
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When the ENTRIES parameter is specified and this is a generic 
LISTCAT, the order in which catalogs are searched when entries 
are to be listed using the LISTCAT command is: 


1. If a catalog is specified in the CATALOG parameter, only 
that catalog is searched. If an entry is not found that 
matches the supplied qualifiers, a "no entry found™ error is 
returned to the user. Otherwise, 


2. <Any user catalog(s) specified in the current job step 
€STEPCAT) or, if none is specified for the job step, any 
user catalog(s) specified for the current job (CJOBCAT). If 
more than one catalog 1s specified for the job step or job, 
the job step or job catalogs are searched in order of 
concatenation. The catalog search continues with step 3 
below. Otherwise, 


3. If the entry's name is a qualified name, and the first 
qualifier (that is, the first 1 to 8 characters before a 
period) is the same as: 

e The name of a user catalog, or 
e The alias of a user catalog, or 
®@ The alias of an OS CVOL, 


that user catalog or OS CVOL is searched. The catalog 
search continues with step 4 below. Otherwise, 


4. The master catalog is searched. If an entry has not been 
found in any of the catalogs search that matched the 
ra ieee qualifiers, a "no entry found" error is returned to 
e user. 


MASS STORAGE SVSTEM (MSS) 


The IBM 3850 Mass Storage System can be used to store a massive 
amount of data online to the operating system. It is described 
in In Od Lon 8 ne Lp 52U Mass Orage . yy we ‘ 


When you have the Mass Storage System, you can define VSAM data 
spaces, user catalogs, and data sets and non-VSAM data sets on 
mass storage volumes. The master catalog cannot be stored ona 
mass storage volume. | 


A catalog may have defined in it both objects stored on direct 
access storage volumes and objects stored on mass storage 
volumes. In particular, the data component of a Key-sequenced 
cluster may be stored on a mass storage volume and the index 
component on a direct access storage volume, or vice versa. 


Space for an object larger than one cylinder that is stored on a 
mass storage volume should be allocated in cylinders to optimize 
data transfer (staging and destaging) between mass storage and 
direct access storage. 


Data stored in the Mass Storage System is staged from mass 
storage to a direct access storage staging drive when the object 
to which the data belongs is opened or when the data is 
requested. It is destaged from the pares drive to mass 
storage when the object is closed. (¢ 

tells which direct access storage 
devices can be used for staging.) 


Access method services for the Mass Storage System provides a 
set of commands for the management of mass storage volumes. 
These commands are described in 7 


Access method services for managing catalogs provides parameters 
for options of the Mass Storage System in the DEFINE and ALTER 
commands, which enable you to specify how a VSAM data set that 
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1s stored on a mass storage volume is to be staged and destaged 
and how a user catalog that is stored on a mass storage volume / 
is to be destaged. These parameters are described in this book. Gi 


Ne w” 
The staging attributes, BIND, CYLINDERFAULT, and STAGE, affect 
performance. BIND causes an object to be staged when it is 
opened and to be retained Cbound) in direct access storage. 
CYLINDERFAULT causes portions of an object to be staged only as 
needed during processing. STAGE is a compromise: the object is 
staged when it is opened, but not retained in direct access 
storage. When the staging activity of other objects is light, 
STAGE can achieve results similar to BIND: the data might 
remain in direct access storage, available for requests for 
access without staging. When the staging activity of other 
objects is heavy, STAGE can achieve results similar to 
CYLINDERFAULT: the data might not remain in direct access 
storage and might have to be restaged when needed. 


ia oe 


A user catalog that is stored on a mass storage volume is always 
staged and bound when it is opened-—that is, it is retained in 
direct access storage until it is closed. Not binding a user 
catalog might degrade performance. 


For recoverable catalogs, a catalog recovery area (CRA) is 
opened when it is first needed, and remains open for as long as 
the user catalog is open. Because of this, the CRA volume must 
remain mounted during that period of time. 


The destaging attributes, DESTAGEWAIT and NODESTAGEWAIT, affect 
data integrity. DESTAGEWAIT causes VSAM to return control to 
the program that closes an object synchronously-—only after 
destaging is complete. VSAM can notify the program whether 
destaging was successful. NODESTAGEWAIT causes VSAM to return 
control to the program asynchronously——as soon as the object is 
closed, but before it has been destaged. 


A failure in destaging causes a message to be written to the 
operator. With DESTAGEWAIT, an error code is also returned from 
CLOSE to the processing program. But there are no recovery 
procedures for a program to undertake: One use of DESTAGEWAIT 
is for a processing program to periodically issue a temporary 
CLOSE of a bound object to cause it to be destaged at various 
checkpoints. The processing program can terminate processing if 
a failure occurs in destaging. The last copy destaged would be 
the copy to fall back to, pending correction of the error that 
caused the failure. 


A data component that is defined with the ERASE parameter and 
stored on a mass-~storage volume, is overwritten with binary 
zeros on the staging drive after it is destaged. 


Note: On mass storage volumes, a GDG data set may not be 


scratched when it is automatically uncataloged, even if the 
SCRATCH option was specified in the DEFINE. 
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This chapter describes: 


e IF-THEN-ELSE command sequence, which is used to control 
command execution on the basis of condition codes 


8 DO-END command sequence, which specifies more than one 
functional access method services command and its parameters 


e NULL command, which specifies that no action is to be taken 
® SET command, which is used to reset condition codes 


® PARM command, which is used to specify diagnostic aids and 
printed output options 


These commands cannot be used when access method services is 
being executed under TSO. 


CONDITION CODES 


The condition codes that are tested in the IF-THEN-ELSE command 
sequence follow: 


Code Explanation 


0 Indicates that the function was executed as directed and 
expected. Some informational messages might be issued. 


4 Indicates that some problem was met in executing the 
complete function, but it was possible to continue. The 
continuation might not provide the user with exactly what 
is wanted, but no permanent harm will have been done by 
such continuation. A warning message was issued. An 
example of the kind of problem encountered is: The system 
was unable to locate an entry in a LISTCAT command. 


8 Indicates that a requested function was completed, but 
major specifications were unavoidably bypassed. For 
example, an entry to be deleted or altered could not be 
found in the catalog, or a duplicate name was found while 
an entry was being defined and the define action was 
terminated. 


l2 Indicates that the requested function could not be 
performed. This condition code is set as a result of a 
logical error. A logical error condition exists when 
inconsistent parameters are specified, when required 
parameters are missing, or when a value specified for key 
length, record size, or buffer space is too small or too 
large. More information on logical errors that occur 
during VSAM record processing is in ini j 


16 Indicates that a severe error occurred that caused the 
remainder of the command stream to be flushed. This 
condition code might result in the following examples: A 
system output data set cannot be opened (Ca SYSPRINT DD 
statement was missing, for example); an unrecoverable error 
occurred in a system data set; or access method services 
encountered improper IF-THEN-ELSE command sequences. 


Condition codes that are tested in the IF-THEN-ELSE command 
sequence or set by the SET command cannot be passed from one job 
step to the next. However, the maximum condition code value 
established by any previous functional command or SET command is 
passed to the operating system when the access method services 
processor returns control to the system. 
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IF-THEN-ELSE COMMAND SEQUENCE 


The IF-THEN-ELSE éoinisand: sequence is used to control command 
execution. 


The format of the IF-THEN-ELSE command sequence is: 


{LASTCC]MAXCC} comparand number 
THENEC command! 





DO 
END] | 
reese! command | 
command 
END] ] 
where: 
IF 


specifies that one or more functional commands ae to be 
executed based on a test of a condition code. 

condition code is set by a SET command or is set to reflect 
the completion status of previous functional commands. 


LASTCC 


specifies that the condition code value that resulted from 
the immediately preceding function command is to be 
compared, as indicated by the comparand, to the number 
following the comparand. For the meaning of condition 
codes, see "Condition Codes." 


MAXCC 





specifies that the maximum condition code value that has eS 


been established by any previous function command or by a 
SET command is to be compared, as indicated by the 
comparand, to the number following the comparand to | 
determine whether the THEN action is to be performed. For 
the meaning of condition codes, see "Condition Codes." 


specifies the comparison to be made between the variable 
and the following number. There are six possible 
comparisons: | 


Equal, specified as '=' or 'EQ* Not equal, specified as 
fez? or "NE 


Greater than, specified as '>' of 'GT' 
Less than, specified as ‘'<' or 'LT' 
Greater than or equal, specified as '>=' or 'GE’ 


Less than or equal, specified as '<=' or "LE! 


number 


THEN 
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specifies the decimal integer that is to be compared with 
MAXCC or LASTCC. The number can be up to 10 digits long. 
Values greater than 16 are reduced to 16; both LASTCC and 
MAXCC are initialized to zero upon entry to access method 
services. For the meaning of condition codes, see = - 
"Condition Codes." 


specifies that a single command or a group of commands 
Cintroduced by DO) is to be executed if the comparison was 
true. THEN can be followed by another IF command. Af 
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ELSE 
specifies that a single command or a group of commands 
Cintroduced by DO) is to be executed if the previous 
ees! is false. ELSE can be followed by another IF 
command. 


When an IF command appears in a THEN or ELSE clause, it is 
called a nested IF command. The maximum level of nesting 
allowed is 10, starting with the first IF specified. 


Within a nest of IF commands, the innermost ELSE clause is 
associated with the innermost THEN clause, the next innermost 
ELSE clause with the next innermost THEN clause, and so on. (To 
Say it another way, each ELSE is matched with the nearest 
preceding unmatched THEN.) Should there be an IF command that 
does not require an ELSE clause, follow the THEN clause with a 
null ELSE clause CELSE), unless the nesting structure does not 
require one. 


DO-END COMMAND SEQUENCE 


NULL COMMANDS 


SET COMMAND 


DO 
specifies that the group of commands that follow is to be 
treated as a single unit, that is, to be executed as a 
result of a single IF command. The set of commands is 
terminated by END. A command following a DO must begin on 
a new line. | 

END 


specifies the end of a set of commands initiated by the 
nearest unended DO. END must be ona line by itself. 


Note: Continuation characters should not be used in the 
DO-END sequence; they may be taken as a null command or 
cause unpredictable results. 


If THEN or ELSE is not followed by a continuation character or 
ee command in the same record, the THEN or ELSE results in no 
action. 


The null command supports an ELSE command that balances an 
IF-THEN-ELSE command sequence, and allows null THEN commands. 
The null command is, in essence, a THEN or ELSE command that is 
not followed by a command continuation character. 


If you want to indicate a null ELSE command, specify: 
ELSE 
If you want to indicate a null THEN command, specify: 
IF ... THEN 
ELSE. «25 
The null command is used to indicate that no action is to be 


taken if the IF clause is satisfied Ca null THEN command), or if 
the IF clause is not satisfied Ca null ELSE command). 


The SET command is used to change or reset a previously defined 
condition code. (For the meaning of condition codes, see 
"Condition Codes.™) It is possible to terminate all processing 
merely by setting MAXCC or LASTCC to 16. 
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The format of the SET command is: 


: SET {MAXCC | LASTCC} =number 


where: 


SET 
specifies that a condition code value is to be set. A SET 
command that follows a THEN or ELSE that is not executed 
does not cause the value of LASTCC or MAXCC to be altered. 


MAXCC | 
specifies that the value to be reset is the maximum 
condition code set by a previous functional command. 
Setting MAXCC does not affect the value of LASTCC. 


LASTCC 
specifies that the value to be reset is the condition code 
set by the immediately preceding functional command. 


number 
specifies the value to be assigned to MAXCC or LASTCC. The 
maximum value that can be assigned is 16; a greater value 
will be reduced to 16. If the value assigned to LASTCC is 
greater than the value of MAXCC, MAXCC is set equal to the 
higher value. 


PARM COMMAND 
The PARM command specifies processing options to be used during 
execution. These options remain in effect until changed by 
another PARM command. You can also specify these options in the 
PARM field of an EXEC statement Cin the JCL) 


The format of the PARM command is: 


[TEST ( 
{ITRACE] 
[AREAS(areaidt areaid...1])] 
PFULL( (dumeidt counti£€ count2)]) 


[(dumpid...)...J3)1] 


OFF} )] 
[ GRAPHICS (CHAIN( chain) | TABLE(mname) )1 
[MARGINS(leftmargin rightmargin)1 





where: 


TEST ( 

{CCI TRACE] 

[AREASlareaidi areaid...1)] 

CFULL((dumpid£ countl£ count2l]) 
[(dumpid...)..Jd)] | 

OFF} ) 
specifies the diagnostic aids to be used. After the TEST 
option has been established, it remains in effect until it 
is reset by another PARM command. The TRACE, AREAS, and 
FULL parameters may be used concurrently. 


TRACE 
specifies that trace tables are to be listed whenever 
the built-in dump points of the processor are 
encountered. 


saad reer areaid...1) 
identifies modules that are to have selected variables 
dumped at their dump points. Each item in the areaid 
is a 2-character area identifier defined within the 
implementation. For more information, see Ac 
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: FULL((dumpidt countl€ count2]11]) 0 (dumpid...)...]) 
| goo. specifies that a region dump, as well as the trace 
( tables and selected variables, is to be provided at 
| the specified points. dumpid specifies the 
G-character identifier of the dump point. For more 
information, see ] ‘Wome 


is a decimal integer that specifies the number of 
times the program is to go through the dump point 
“ta beginning the dump listing. (Default is 


is a decimal integer that specifies the number of 
times through the dump point that dumps are to be 
listed. (Default is 1.) 


If the FULL keyword is used, an AMSDUMP DD statement 
must be provided. For example: 


//7AMSDUMP DD SYSOUT=A 


OFF 
specifies that testing is to stop. 


GRAPHICS (CHAIN( chain) [| TABLE(mname) ) 
specifies the print chain graphic character set or a 
special graphics table to be used in producing the output. 


CHAIN(CAN| HN] PNIQNIRNISNITN) 
specifies the graphic character set of the print 
chains you want to use. PN is used by the processor 
unless explicitly directed to use another set of 
graphics. 


( TABLE (mname) 

; specifies the name of a user-supplied table. This 
256-byte table defines the graphics for each of the 
256 possible bit patterns. Any character to be 
printed is translated to the bit pattern found in such 
a table at the position corresponding to its numeric 
value (0 through 255). If the print chain does not 
have a graphic for a byte's bit pattern, the table 
should specify a period as the output graphic. The 
table must be stored as a module accessible through 
the LOAD macro (VS). 


MARGINS(leftmargin rightmargin) 
specifies that the margins of input records on which 
command statements are written are to be changed. The 
normal left and right margins are 2 and 72, respectively. 
If MARGINS is coded, all subsequent input records are 
scanned in accordance with the new margins. This feature 
may be used in conjunction with the comment feature: 
Respecification of margins could be used to cause the /*X 
and ¥/ characters to be omitted from the scan and thus 
cause comments to be treated as commands. 


specifies the location of the left margin. 


specifies the location of the right margin. The right 
deat et value must be greater than the left margin 
value. 
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COMMON CONTINUATION ERRORS IN CODING CONTROL COMMANDS 


The continuation rules must be used cautiously when modal _—_ 
commands appear in the input stream. (See "How to Continue ae, 
Commands and Parameters" on page 7.) The following examples ~ 
show common continuation errors: | 
e IF LASTCC = 0 - 

THEN 

LISTCAT 

A continuation mark (hyphen) is missing after the THEN 

keyword. A null command is assumed after the THEN keyword, 

and the LISTCAT command is unconditionally executed. 
@ IF LASTCC = 0 - 

THEN - 

REPRO ... 

/X¥ALTERNATE PATHX/ 

ELSE - 

PRINT 

Because no continuation mark Chyphen) follows the comment, a 

null command is assumed. The ELSE keyword will not match up 

with the THEN keyword. Note the correct use of the 

continuation marks on the other records. 
e IF LASTCC = 0 - 

THEN - 

REPRO ... 

ELSE - 

PRINT 

Because a blank line with no continuation mark Chyphen) 

follows the ELSE keyword, the ELSE becomes null and the : 

PRINT command is unconditionally executed. : 

7 

° PARM TEST € ~- /XCOMMENTX/ “ 

TRACE) 

Because characters other than blanks appear between the 

continuation mark Chyphen) and the end of the record, the 

PARM command will not be continued onto the second record. 
8 PARM TEST € TRAt+ 

/X¥FIELD CONTINUATIONX7 

CE) 

Because no continuation was indicated, the end of the PARM 

command is found after the second record. The command is 

rejected. 
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CONTROL COMMAND EXECUTION EXAMPLES 


a | The examples that follow show the use of the IF-THEN-ELSE 
7 command sequence, the SET command, and the PARM command. 


Control Command Execution with Nested IF Commands: Example 1 


In this example, nested IF commands are used to determine 
whether a REPRO, DELETE, or PRINT command is to be executed. 


IF LASTCC > 4 - 
THEN IF MAXCC < l2 - 
THEN REPRO... 
ELSE DELETE... 
ELSE IF LASTCC = 4 - 
THEN 
ELSE PRINT... 


This example specifies that, if the value of LASTCC is greater 
than 4, the value of MAXCC is to be tested. If the value of 
MAXCC is less than 12, the REPRO command is executed; if the 
value of MAXCC is 12 or greater, the DELETE command is executed 
instead. Again, if the value of LASTCC is 4 or less, LASTCC is 
tested for being exactly 4: No action is to be taken in this 
case. If, however, LASTCC is less than 4%, the PRINT command is 
to be executed. 


Control Command Execution with Nested IF Commands: Example 2 


In this example, nested IF commands are used to determine 
whether a REPRO or PRINT command is to be executed. 


IF LASTCC >G@ - 
— THEN IF MAXCC < 12 - 
( THEN REPRO ... 


ELSE 
ELSE IF LASTCC = 4 - 
THEN PRINT ... 


Should the first IF command determine that LASTCC is greater 
than 4, and the second IF command determine that MAXCC is 12 or 
greater, no functional commands will be executed. The null ELSE 
command is employed here to specify that the next ELSE is to 
correspond to the first THEN. 


Control Command Execution Using MAXCC Parameter: Example 3 


In this example, if the maximum condition code is 0, an entry 
from a catalog is listed and a data set is printed. 


IF MAXCC=0 THEN DO 
LISTCAT CATALOG CAMASTCAT/MST27) ENT (MNO1.0005) 
PRINT INFILE CAJK006) 
END 
ELSE. ao% 
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Control Command Execution Using LASTCC Parameter: Example 4 


If you want to list a catalog and print a data set if the last fo 
condition code is 0, but want to list its catalog entry before N 


rea 
and after a VERIFY command if the last condition code is greater id 
than 0, specify: 


IF LASTCC = 0 THEN DO 
LISTCAT 
PRINT INFILE CAJKO06) 
END 


ELSE DO | 
LISTCAT ENTRY CAJK006) ALL 
VERIFY FILE CAJKJCL6) 
aan ENTRY CAJK006) ALL 


Control Command Execution with LASTCC Value Established: Example 5 


If you want to set the last condition code established to 12, 
specify: 


SET LASTCC=12 


Control Command Execution Replacing MAXCC Value: Example 6 


If you want to replace the highest condition code established in 
processing so far with 8, specify: 


SET MAXCC=8 
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This chapter contains the access method services functional 7 
commands for VSAM catalogs, 0S CVOLs, and for VSAM and non-VSAM 
data sets. The commands are arranged alphabetically, with a 
summary of the required and optional parameters following each 
command section. The required parameters are arranged in 
alphabetic order, with a discussion of the parameter and an 
abbreviation following. The optional parameters are in the same 
format and follow the required parameters. 


Examples of how each command is used are provided at the end of 
each command. 


For an explanation of the symbols used in the command formats, 
see "Notational Conventions™ on page vi. See "How to Code 
Subparameters™ on page 5 for coding conventions that apply to 
the subparameters used in access method services commands. 


FUNCTIONAL COMMAND FORMAT SUMMARY 


This section provides reference information about the following 
functional commands. 


® ALTER, which is used to alter attributes of data sets and 
catalogs that have already been defined. 


® ed which builds alternate indexes for existing data 
sets. 


e CHKLIST, which lists tape data sets opened during a 
checkpoint. 


° CNVTCAT, which converts OS CVOL entries into VSAM catalog 
entries. 


® DEFINE, which defines the following objects: 


— DEFINE ALIAS, which defines an alternate name for a 
non-VSAM data set or a user catalog. 


a DEFINE ALTERNATEINDEX, which defines an alternate index. 


- DEFINE CLUSTER, which defines a cluster for a 
ee a aaa entry~sequenced, or relative record data 
set. 


= DEFINE GENERATIONDATAGROUP, which creates a catalog 
entry for a generation data group. 


DEFINE NONVSAM, which defines a catalog entry for a 
non-VSAM data set. 


a DEFINE PAGESPACE, which defines an entry for a page 
space data set. 


a DEFINE PATH, which defines a path directly over a base 
cluster or over an alternate index and its related base 
cluster. 

aa, DEFINE SPACE, which defines a VSAM data space. 


— DEFINE USERCATALOG|MASTERCATALOG, which defines a user 


catalog. 
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° DELETE, which deletes catalogs, VSAM data sets, and non-VSAM 
data sets. 





e EXAMINE, which is used to analyze and report on the 
structural consistency of the index component and/or data 
component of a key-~sequenced data set cluster. 


e EXPORT, which disconnects user catalogs and exports VSAM 
data sets. 


° EXPORTRA, which recovers VSAM and non-VSAM catalog entries 
from catalog recovery areas, and recovers data for VSAM 
objects (clusters and alternate indexes) by means of catalog 
recovery areas. | 


@ ai which connects user catalogs and imports VSAM data 
sets. | | 


e IMPORTRA, which reconstructs multiple VSAM data sets from a 
data set created by the EXPORTRA command. 


e LISTCAT, which lists catalog entries. 


e LISTCRA, which lists or compares the contents of a given 
catalog recovery area. 


e PRINT, which is used to print VSAM data sets, non-VSAM data 
sets, and catalogs. 


e REPRO, which is used to copy VSAM and non-VSAM data sets, to 
copy catalogs, and to unload and reload VSAM catalogs. 


e RESETCAT, which compares catalog entries with catalog 
recovery area (CRA) entries in order to regain access to 
catalog data. 


e VERIFY, which causes a catalog to correctly reflect the end 
of a data set after an error occurred while closing a VSAM 2 
data set. The error may have caused the catalog to be _ 
incorrect. 
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ALTER 


-_ The ALTER command modifies the attributes of previously defined 
| catalog entries. The format of this command is: 


entrynamel /password] 
[ADDVOLUMES(yvolser[I yolser...1)] 
CLATTEMPTS (number J] 
PAU HORT ZATION entrypoantt string])1 
[BUFFERSPACE(size)] 
[CODE(code)] 
[CONTROLPW( password)] 
[DESTAGEWAIT | NODESTAGEWAITI 
[EMPTY | NOEMPTY] 
[ERASE | NOERASE] 
[LEXCEPTIONEXITlCentrvpoint)] 
[FILE(ddnameJ] 
[FREESPACE(CI-percent£ CA-percent])] 
CINHIBIT|UNINHIBITI 
CKEYS( offset 
PAS TE REW (password) 
[NEWNAME (newname)] 
[NULLIFY( 
[ AUTHORIZATION( MODULE [STRING) J 
[CODE] 
[CONTROLPW] 
[EXCEPTIONEXIT] 
[MASTERPW] 
[OWNER] 
[READPW] 
[RETENTION] 
[UPDATEPW])1 
LOWNER( ownerid)] 
CREADPW( password) 1 
e [RECORDSIZE(average maximum)! 
i CREMOVEVOLUMES(volser[ volser...1)] 
| [SCRATCH] NOSCRATCH] 
) CSHAREOPTIONS(crossregionl crosssystem])1 


[STAGE | BIND] CYLINDERFAULT] 
[TO(date) [FOR(days)] 

[UNI QUEKEY | NONUNIQUEKEY] 
[UPDATE | NOUPDATE] 
[UPDATEPW( password)] 

[ UPGRADE | NOUPGRADE ] 
[WRITECHECK | NOWRITECHECK] 





[CATALOG(catnamel/password1])]1 


Entry Types That Can Be Altered 


An "X™ ain Figure 2 on page 32 indicates you can alter the value 
or attribute for the type of catalog entry specified. KEYS and 
RECORDSIZE, when specified for a cluster or alternate index, 
apply to its data component entry only, and not to the cluster 
or alternate index entry. Some attributes can be specified only 
for the cluster's or alternate index's data or index component 
entry—you must identify the component with its entryname. You 
can use the LISTCAT command to determine the names generated for 
the object's components. 


When you identify a group of entries with a generic name, 
entries whose entrynames match the supplied qualifiers are 
altered if they contain the type of information specified with 
the ALTER command's other parameters. 


You cannot alter the following types of entries: alias entries, 
a catalog's data or index component entries, or a master 
catalog's self-describing entries. 
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ADDVOLUME 
AUTHORIZATION 
BUFFERSPACE 
CYLINDERFAULT 
DESTAGEWAIT 
EXCEPTIONEXIT 
NODESTAGEWAIT 
NOUNIQUEKEY 
NOSCRATCH 
NOUPGRADE 
NOWRITECHECK 


= 
a. 
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O 


ATTEMPTS 
CODE 
EMPTY 
FREESPACE 
INHIBIT 
KEYS 
MASTERPW 
NOEMPTY 
NOERASE 
NOUPDATE 





ALTER Parameters and the Entry Types to Which Each Applies 


Figure 2 (Part 1 of 2). 
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Figure 2 (Part 2 of 2). ALTER Parameters and the Entry Types to Which Each Applies 
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ALTER 
ALTER PARAMETERS 


Required Parameters 





entrynamel/password!] 


Optional Parameters 


names the entry to be altered and supplies a password. 


When attributes of a catalog are to be altered, entryname 
must specify the catalog name. 


For a description of how to specify a generic name in order 
to alter multiple entries with one ALTER command, see 

. See this guide also for a 
description of how to alter data or index entrynames or 
cluster entry subparameters. 


If you are renaming a member of a non-VSAM partitioned data 
set, the entryname must be specified in the format 
pdsname(Cmembername). 


specifies the password of the entry or catalog to be 
altered. 


If you are altering a password-protected entry in a 
password-protected catalog, you must specify a 
password. The password can be specified with the 
entryname or in the CATALOG parameter. 


° Use the master password for the entry or for the 
catalog that contains the entry for an alternate 
index, cluster, page space, path, user catalog, 
data, or index. RACF: The alter RACF authority 
for an entry or for the catalog is required. 


e If a data or index component entry is to be 
altered, use the master password of the cluster 
component or catalog. RACF: The alter RACF 
authority for a cluster component or a catalog is 
required. 


° Use the update- or higher-level password of the 
catalog that contains the entry for non-VSAM and 
generation data group (GDG). RACF: The update or 
higher RACF authority to the catalog is required. 


ADDVOLUMES (volserlvolser]) 


specifies volumes to be added to the list of candidate 
volumes. When you specify ADDVOLUMES, the FILE parameter 
must also be specified to identify the volumes being added. 
The volumes to be added as candidate volumes must already 
be owned by the catalog that contains the entry being 
altered. (Space must have been defined on a volume to be 
added or the volume must have been identified as a 
candidate volume.) 


Abbreviation: AVOL 


ATTEMPTS (number) 
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specifies the maximum number of times the operator can try 
to enter a correct password in response to a prompting 
message. 


This parameter only has effect when the entry's master 


password is not null. A prompting message is issued only 
if the user has not already supplied the appropriate i‘ 


yer 
ra 


password. | eu 
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ALTER 


number : : 
Mien is an integer from 0 to 7 and can be expressed in 
( ocat a> (nd), hexadecimal €X"n"), or binary CB tn') 
| orm. 


When ATTEMPTS(0) is coded, the operator is not 
prompted and is not allowed to enter a password from 
the console. 


Note te TSO users: At a TSO terminal, the logon 
password is checked first, before the user is prompted 
to supply a password. Checking the logon password 
counts as one attempt to obtain a password. f 
ATTEMPTS is not specified, the user has one attempt to 
supply the password, because the default is 2. 


Abbreviation: ATT 
AUTHORIZATION(entrypointl( stringl]) 


specifies that a user-security-verification routine CUSVR) 
1s available for additional security verification. 


specifies the name of the USVR. 


specifies information to be passed on to the USVR when 
it receives control to verify authorization. 


Abbreviation: AUTH 


BUFFERSPACE(size) 
specifies the minimum space to be provided for buffers. 


It is recommended that the amount specified be not less 
Nien than the amount specified in the original definition. If 
BS the amount is less, VSAM attempts to get enough space to 
contain two data component control intervals and, if the 
data is key-sequenced, one index component control 
interval. BUFFERSPACE can be specified only for a catalog, 
or the data component of a cluster or alternate index. 


Sil2e2 
specifies the amount of space to be provided for 
buffers. If you are altering the bufferspace for a 
VSAM catalog on a 3380, the decimal values you can 
specify are 4096, 61449, 8192, 10290, 12288, and 14336. 
If you are altering the bufferspace for a VSAM catalog 
not residing on a 3380, the decimal values you can 
me ee limited to 3072, 4608, 61449, 7680, 9216, 
an ‘ 


Size can be expressed in decimal (n), hexadecimal 
CX'n'), or binary CB'n') form, but must not exceed 
16776704. If the size specified is less than the 
amount VSAM requires, VSAM gets the amount it requires 
when the data set is opened. 


Abbreviations: BUFSP or BUFSPC 
CATALOG( catnamel/password]) 


specifies the catalog containing the entry to be altered. 
See "Order of Catalog Search for ALTER™ on page 15 for 
information about the order in which catalogs are searched. 


specifies the name of the catalog that contains the 
entry. 


password | 
specifies the master password of the catalog that 
contains the entry to be altered. If the entry to be 
altered is password-protected and the catalog is also 
password-protected, a password must be entered, either 
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ALTER 


through this parameter or through the entryname 
parameter. RACF: The alter RACF authority to the rs 
catalog is required. i 





Abbreviation: CAT 


CODE( code) 
specifies a code name for the entry being altered. If an 
attempt is made to access a password protected entry 
without a password, the code name is used in a prompting 
message. The code enables the operator or TSO terminal 
user to be prompted for the password without disclosing the 
name of the entry. 


If CODE is not specified and an attempt is made to access a 
cluster or component that is password protected without 
supplying a password, the operator or TSO terminal user is 
prompted with the name of the entry. 


CONTROLPW( password) 


specifies a control password for the entry being altered. 
Abbreviation: CTLPW 


DESTAGEWAIT | NODESTAGEWAIT 
specifies whether a data or index component that is stored 
on a mass storage volume is to be destaged synchronously or 
asynchronously, with respect to the program that closes it. 


These parameters can be specified only for the data or 
index component of a cluster, alternate index, or 
integrated catalog facility catalog. 


DESTAGEWAIT 
indicates that destaging is to be completed before 
control is returned from VSAM to the program that gtx 
issues the CLOSE macro. VSAM can thus notify the \ 
program whether destaging was successful. ee J 
Abbreviation: DSTGNW 

NODESTAGEWAIT 


indicates that notification of unsuccessful destaging 
is to be made only by a message to the operator. 


Abbreviation: NDSTGW 


EMPTY | NOEMPTY 
specifies what is to happen when the maximum number of 
generation data sets has been cataloged. 


EMPTY 
specifies that, when the maximum number of generation 
data sets is exceeded, all the generation data sets 
will be uncataloged. 


Abbreviation: EMP 


NOEMPTY 
specifies that when the maximum number of generation 
data sets is exceeded, only the oldest generation data 
set will be uncataloged. 


Abbreviation: NEMP 


36 MVS/7XA VSAM Catalog: Access Method Services Reference 





























ALTER 


ERASE | NOERASE 
a specifies whether the data component is to be erased when 
( | its entry in the catalog is deleted. 


ERASE 
specifies the component is to be overwritten with 
binary zeros when its catalog entry is deleted. 


Abbreviation: ERAS 


NOERASE 
specifies the component is not to be overwritten with 
binary zeros when its catalog entry is deleted. 


Abbreviation: NERAS 
EXCEPTIONEXIT(entrypoint) 


specifies the name of the user-written routine that 
receives control when an exception (usually an I/0 error) 
occurs while the entry's object is being processed. 


An exception is any condition that causes a SYNAD exit to 
be taken. The object's exception exit routine is processed 
first, then the user's SYNAD~exit routine receives control. 


Note: You may not specify this parameter to add an 
exception-exit routine to a VSAM cluster that is cataloged 
in a VSAM catalog created in an OS/VS2 Release 2 Cor lower 
release level) system. 


Abbreviation: EEXT 
FILE(ddname) 


specifies one of the following: 


tins e The name of a DD statement that identifies the volume 
whose catalog recovery area contains a copy of the 

| catalog entry. For a description of catalog recovery 

area contents for each volume, see Catalog 


hy 


e The name of a DD statement that identifies the volume 
of an entry which will be renamed. The entry must be a 
non-VSAM data set or the data or index component of a 
unique cluster, alternate index, or page space. 


° The name of a DD statement that identifies a 
partitioned data set when a member is to be renamed. 


If multiple volumes of different device types are to be 
identified via FILE, you must use concatenated DD 
statements. If you specify ADDVOLUMES or REMOVEVOLUMES, 
the volume(s) being added or removed must be identified. 

If you specify NEWNAME for a non-VSAM data set or the data 
or index component of a unique cluster, alternate index, or 
page space that does not reside on the same volume as the 
catalog recovery area entry, that volume(s) must be 
identified. 


If FILE is not specified, an attempt is made to dynamically 
allocate the catalog recovery area volume(s) or the 
object's volume. Therefore, the volume must be mounted as 
permanently resident or reserved. 


FREESPACE(CI-percenti£ CA-percent]) 
specifies the amount of space (percentage of space) that is 
to be left free after any allocation and after any split of 
control intervals (CI-percent) and control areas 
(CA-percent). 


The amounts, as percentages, must be equal to or less than 
100. They may be expressed in decimal (n), hexadecimal 
(X'n'"), or binary CB'n') form. If you specify 100% of free 





Chapter 4. Functional Command Format 37 








ALTER 


space, one record is placed in each control interval and 
one control interval is placed in each control area. 


This parameter may be specified to alter the data component 
of a cluster or alternate index. 


If the free space is altered after the data set has been 
loaded, and sequential insert strategy processing is being 
used, this allocation of free space may not be honored. 


Abbreviation: FSPC 


INHIBIT | UNINHIBIT 


specifies whether the entry being altered can be accessed 
for any operation or only for read operations. 


INHIBIT 
specifies that the entry being altered is to be 
read-only. 


Abbreviation: INH 


UNINHIBIT 
specifies that the read-only restriction set by a 
previous ALTER or EXPORT command is to be removed. 


Abbreviation: UNINH 


KEYS(length offset) 
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specifies the length and offset of the object's key. If 
the entry being altered defines an alternate index, offset 
applies to the alternate key in the data records in the 
base cluster. 


Restrictions: Keys can be specified only if all the 
following are true: 


® The object whose entry is being altered is an alternate 
index, a path, a key~sequenced cluster, or a data 
component of a Key-~sequenced cluster or alternate 
index. 


e The object whose entry is being altered contains no 
data records. 


¢ The values for KEYS in the object's catalog entry are 
default values. For default values, see the DEFINE 
command that defines the object. 


Note: If the values for KEYS in the object's catalog 
entry are not default values, and ALTER KEYS specifies 
the same nondefault values, processing continues for 
any other parameters specified on the command, and no 
error message is issued. 


¢ The new values for KEYS do not conflict with the 
os interval size specified when the object was 
efined. 


e The key fits within the record whose length is 
specified by the RECORDSIZE parameter. 


e The key fits in the first record segment of a spanned 
record. 


denath offset 

specifies the length of the key (between 1 and 255), 
in bytes, and its displacement from the beginning of 
the data record, in bytes. You can express length and 
offset in decimal (n), hexadecimal (X'n"), or binary 
CBin') form. ) 
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ALTER 
MASTERPW( password) 


a! specifies a master password for the entry being altered. 
- For more details about the object's master password, see 
| the DEFINE command that defines the object. 


e If MASTERPW is not specified, the highest level 
oleae specified becomes the password for all higher 
evels. 


e The AUTHORIZATION, CODE, and ATTEMPTS parameters have 
no effect unless the entry has a master password 
associated with it. 


@ With the master password, all operations are allowed. 


Note: The master password must exist to alter lower-level 
passwords. It must be the last level of authority to be 
altered when nullifying all levels of authority. 


Abbreviation: MRPW 


NEWNAME ( newname ) 
specifies that the entry to be altered is to be given a new 
name. 


To give the altered entry a new name: 


e Unless the object being renamed is a path, the object's 
volume ae be mounted because the volume's VTOC is 
modified. 


You can use the FILE parameter to supply a JCL DD 
statement to cause the object's volume(s) to be 
allocated. If you do not supply a DD statement, an 
attempt is made to dynamically allocate the object's 
— volume(s). The volume(€s) must be mounted as either 
( permanently resident or reserved. 


8 If you specify generic names, you must specify both the 
entryname and the newname aS generic names. For 
information on specifying generic names, see Catalog 


° If you are renaming a member of a non-VSAM partitioned 
data set, the newname must be specified in the format: 
pdsname(membername). 


& If you are renaming a VSAM data set that is RACF 
protected, the existing RACF data set profile will be 
renamed. 


° If a data set profile exists for the new data set name 
prior to the ALTER command, the command is terminated 
and the data set name and/or protection attributes 
remain unchanged. 


If the old profile cannot be found or cannot be altered 
to the new name, the NEWNAME action will not be 
completed in the catalog, and an error message will 
indicate why the action was not completed. 


If the rename fails, it is possible that the object 
exists with both the original and the new name. 


Abbreviation: NEWNM 


NULLIFY( L[AUTHORIZATION( MODULE |STRING)] 

[CODE] [LCONTROLPW] [LEXCEPTIONEXIT] 

[MASTERPWI] [OWNER] EREADPWI 

[RETENTION] CUPDATEPW] ) 
specifies that the protection attributes identified by 
subparameters of NULLIFY are to be nullified. Attributes 
are nullified before any respecification of attributes is 
performed. 
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If all levels of passwords are nullified and none are 
ee CODE, AUTHORIZATION, and ATTEMPTS have no 
effect. 


Abbreviation: NULL 


AUTHORIZATION( MODULE| STRING) 
specifies that either the user-~authorization routine 
or the user~-authorization record is to be nullified. 


Abbreviation: AUTH 


MODULE 
specifies that the module name is to be removed 
from the catalog record, but the module itself is 
not to be deleted. Both the user-authorization 
routine and the user-authorization record 
(character string) are nullified. 


Abbreviation: MDLE 


STRING 
specifies that the authorization record is to be 


nullified, but the corresponding module is not 
nullified. 


Abbreviation: STRG 
CODE 


specifies that the code name used for prompting is to 
be nullified. 


CONTROLPW 
specifies that the control password is to be 
nullified. | 
Abbreviation: CTLPW 

EXCEPTIONEXIT 


specifies that the entry's exception exit is to be 
nullified. The module name is removed from the 
catalog record, but the exception-exit routine itself 
is not deleted. 


Abbreviation: EEXT 


MASTERPW 
specifies that the master password is to be nullified. 
If a new master password is not specified and if other 
passwords exist, the highest level password that 
exists automatically becomes the password for all 
higher levels, including the master password. 


Abbreviation: MRPW 


OWNER 


specifies that the owner identification is to be 
nullified. 


READPH 
specifies that the read password is to be nullified. 


Abbreviation: RDPW 


RETENTION 
specifies that the retention period which was 
specified ina TO or FOR parameter is to be nullified. 


Abbreviation: RETN 


UPDATEPW 
specifies that the update password is to be nullified. 


Abbreviation: UPDPW 
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ALTER 
OWNER (ownerid) 


ers: specifies the owner identification of the entry being 
: altered. | 


READPW( password) 


specifies a read password for the entry being altered. 
Abbreviation: RDPW 


RECORDSIZElaverage maximum ) 
specifies new average and maximum lengths for data records 
ni will be contained in the object whose entry is being 
altered. | 


If the object whose entry is being altered is a path 
pointing to the alternate index, the alternate index is 
altered; if it is a path pointing directly tec the base 
cluster, the base cluster is altered. 


If the object whose entry is being altered is an alternate 
index, the length of the alternate key must be within the 
limit specified by maximum. 


Restrictions: RECORDSIZE can be specified only if all of 
the following are true: 


e The object whose entry is being altered is an alternate 
index, a cluster, a path, or a data component. 


e The object whose entry is being altered contains no 
data records. 


@ The value for maximum RECORDSIZE in the object's 
catalog entry is the default value. For default 
values, see the DEFINE command that defines the object. 


( Note: If the value for RECORDSIZE in the object's 

: catalog entry is not the default value, and ALTER 
RECORDSIZE specifies the same nondefault value, 
processing continues for any other parameters specified - 
on the command, and no error message is issued. 


e For an alternate index, if NONUNIQUEKEY is specified, 
the record length to be specified accounts for the 
increased record size resulting from the multiple 
prime-key pointers in the alternate index data record. 


® The maximum record length to be specified is at least 
seven bytes less than control interval size, unless the 
record is a spanned record. 


e The record length to be specified is large enough to 
Ft beat all prime and alternate keys previously 
efined. 


Abbreviation: RECSZ 
REMOVEVOLUMES(volser[ volser]) 


has two uses: 


1. REMOVEVOLUMES specifies volume(s) to be removed from 
the list of candidate volumes associated with the entry 
being altered. If you are also adding volumes, the 
volumes to be removed are removed after the new volumes 
are added to the candidate list. The name of the data 
or index component must be specified in the entryname 
parameter. 


Note: If a volume to be removed contains data that 
apace to the entry being altered, the volume is not 
removed. 


2. REMOVEVOLUMES specifies volume(s) from which all VSAM 
data spaces are to be removed and VSAM ownership is to 
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be taken away-—without access to the user catalog that 
owns the volume(s). For this use of REMOVEVOLUMES, the 
name of the master catalog and its master password (if 
any) must be specified in the entryname parameter, and 
the FILE parameter is required. CYou can have anly one 
DD statement with this use of ALTER REMOVEVOLUMES~——only 
volumes of the same device type can be processed. ) 


For information and cautions about this use of ALTER 
REMOVEVOLUMES, see the sections "VSAM Volume Cleanup™ and 
"VSAM Volume Recovery Function™ in the Catalog 


r 


Abbreviation: RVOL 
SCRATCH | NOSCRATCH 


specifies 


whether generation data sets, when they are 


uncataloged, are to be removed from the VTOC of the volume 
on which they reside. 


SCRATCH 


indicates that the data set's format-1 DSCB is to be 
removed (scratched) from the VTOC so that the data set 
can no longer be accessed. 


Abbreviation: SCR 


NOSCRATCH 


indicates that the data set's format-1 DSCB is not to 
be removed from the VTOC. 


Abbreviation: NSCR 


SHAREOPTIONS(crossregionl! crosssystem] ) 
specifies how a data or index component of a cluster or 


alternate 


index can be shared among users. (For a full 


description of data set sharing, see 
J oo 


specifies the amount of sharing allowed among regions 
within the same system or within multiple systems 
using global resource serialization (GRS). 
Independent job steps in an operating system or 
multiple systems using GRS can access a VSAM data set 
concurrently. 


To share a data set, each user must specify DISP=SHR 
in the data set's DD statement. The values that can 
be specified are: | 


1 


specifies that the data set can be shared by any 

number of users for read processing, or the data 

set can be accessed by only one user for read and 
write processing. With this option, VSAM ensures 
complete data integrity for the data set. 


specifies that the data set can be accessed by 
any number of users for read processing and it 
can also be accessed by one user for write 
Processing. With this option, VSAM ensures write 
integrity by obtaining exclusive control for a 
control interval when it is to be updated. 


If a user requires read integrity, it is that 
user's responsibility to use the ENQ and DEQ 
macros appropriately to provide read integrity 
for the data obtained by the program. (For 


information on using oo and DEQ, see System 
M . Facdlaki es. 
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specifies that the data set can be fully shared 
by any number of users. With this option, each 
user 1s responsible for maintaining both read and 
write integrity for the data the program 
accesses. 


User programs that ignore the write integrity 
guidelines can cause VSAM program checks, lost or 
inaccessible records, uncorrectable data set 
failures, and other unpredictable results. This 
option places heavy responsibility on each user 
sharing the data set. 


specifies that the data set can be fully shared 
by any number of users and buffers used for 
direct processing are refreshed for each request. 


This option requires the program to use the ENQ 
and DEQ macros to maintain data integrity while 
sharing the data set. Improper use of the ENQ 
macro can cause problems similar to those 
described under SHAREOPTIONS 3. (For information 
on re aes and DEQ, see System Macros and 


specifies the amount of sharing allowed among systems. 
Job steps of two or more operating systems can gain 
access to the same VSAM data set regardless of the 
disposition specified in each step's DD statement for 
the data set. 


To get exclusive control of the data set's volume, a 
task in one system issues the RESERVE macro. The 
level of cross~system sharing allowed by VSAM applies 
only ina multiple operating system environment. The 
values that can be specified are: 


1 
Reserved 


2 


Reserved 


specifies that the data set can be fully shared. 
With this option, each user is responsible for 
maintaining both read and write integrity for the 
data the program accesses. 


User programs that ignore write integrity 
guidelines can cause VSAM program checks, 
uncorrectable data set failures, and other 
unpredictable results. This option places heavy 
responsibility on each user sharing the data set. 


specifies that the data set can be fully shared. 
Buffers used for direct processing are refreshed 
for each request. 


This option requires that you use the RESERVE and 
DEQ macros to maintain data integrity while 
sharing the data set. (For information on using 
Sle and DEQ, see 

Writing is limited to PUT~update 
and PUT- insert processing that does not change 
the high used RBA if your program opens the data 
set with DISP=SHR. 


Data set integrity cannot be maintained unless 
all jobs accessing the data set in a cross-system 
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environment specify DISP=SHR. Improper use of Bett 
the RESERVE macro can cause problems similar to — 


those described under SHAREOPTIONS 3. ‘“\S 


Abbreviation: SHR 
STAGE! BIND|CYLINDERFAULT 
specifies how a data or index component that is stored ona 
mass storage volume is to be staged. 
These parameters can be specified only for the data or 
index component of a cluster or alternate index. 
STAGE 
indicates that the component is to be staged from mass 
storage to a direct access storage staging drive when 
the component is opened. 
BIND 
indicates that the component is not only to be staged, 
but also bound Cor retained) on the direct access 
storage staging drive until it is closed. 
CYLINDERFAULT 
indicates that the component is not to be staged when 
it 1s opened, but that data from it is to be staged as 
the processing program needs it. 
Abbreviation: CYLF 
TO( date) | FOR( days) 
specifies the retention period for the entry being altered. 
These parameters cannot be specified for the data or index 
components of clusters, alternate indexes, or catalogs. In 
the case of a non-VSAM data set the expiration date in the 
catalog will be updated, but the expiration date in the 
format-1 DSCB will not be changed. 
TOlCdate) 
specifies the date, in the form yyddd, where yy is the 
year and ddd is the number (001 through 365) of the 
day through which the entry is to be kept. 
FOR( days) 
specifies the number of days for which the entry is to 
gegen The maximum number that can be specified is 
If the number specified is 0 through 1830, the cluster 
is retained for the number of days specified; if the 
number is between 1831 and 9999, the cluster is 
retained through the year 1999. 
days ; : 
can be expressed in decimal (n), hexadecimal 
CX'n'), or binary (B'n'") form. 
UNIQUEKEY | NONUNIQUEKEY 
specifies whether the alternate-key value can be found in 
more than one of the base cluster's data records. 
UNIQUEKEY 
specifies that each alternate-key value is unique. If 
the same alternate-key value is found in more than one 
of the base cluster's data records, an error results. 
UNIQUEKEY can be specified only for an empty alternate 
index (that is, an alternate index that is defined but Soe. 
not yet built). fd . 
Abbreviation: UNQK a 
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: NONUNIQUEKEY 
Cee specifies that a given alternate-key value might point 
( to more than one data record in the cluster. 


NONUNIQUEKEY can be specified for an alternate index 
at any time. 


If the alternate index is empty, you should also 
consider specifying RECORDSIZE to ensure that each 
alternate index record is large enough to contain more 
than one data record pointer. 


Abbreviation: NUNQK 


UPDATE | NOUPDATE 
specifies whether a base cluster'’s alternate index upgrade 
set is to be allocated when the path's name is allocated. 


UPDATE 
specifies that the cluster's alternate index upgrade 
set is to be allocated when the path's name is 
allocated with a DD statement. 


Abbreviation: UPD 


NOUPDATE 
specifies that the cluster's alternate index upgrade 
set is not to be allocated but the path's cluster is 
to be allocated. 


Note: If the path is opened specifying NOUPDATE and 
sharing a control block structure which specifies 
UPDATE, the upgrade set has been allocated and the 
upgrade set may be updated. 


2 Abbreviation: NUPD 
( UPDATEPW( password) 


specifies an update password for the entry being altered. 
Abbreviation: UPDPW 


UPGRADE | NOUPGRADE 
specifies whether an alternate index is to be upgraded 
ane ar kept up to date) when its base cluster is 
modifie 


UPGRADE 
specifies that the cluster's alternate index is 
upgraded (to reflect the changed data) when the 
cluster's records are added to, updated, or erased. 


If UPGRADE is specified when the cluster is open, the 
upgrade attribute does not apply to the alternate 
index until the cluster is closed and then opened 
(that is, a new set of VSAM control blocks describes 
the cluster and its attributes). 


UPGRADE can be specified only for an empty alternate 
index (that is, an alternate index that is defined but 
not built). However, the UPGRADE attribute is not 
effective for the alternate index until the alternate 
index is built (see the BLDINDEX command). 


Abbreviation: UPG 

NOUPGRADE 
specifies that the alternate index is not modified 
when its base cluster is modified. NOUPGRADE can be 
specified for an alternate index at any time. 


( Abbreviation: NUPG 
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WRITECHECK | NOWRITECHECK 
specifies whether a data or index component is to be / | 
checked by a machine action called write check when a a Y 
record is written into it. 


This parameter may be specified to alter the data or index 
components of a cluster or an alternate index. 


WRITECHECK 
specifies that a record is to be written and then 
read, without data transfer, to test for the data 
check condition. 


Abbreviation: WCK 


NOWRITECHECK 
specifies that a record is to be written only. 


Abbreviation: NWCK 
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ALTER EXAMPLES 


Alter a Cluster's Attributes: Example 1 


In this example, an ALTER command is used to specify passwords 
for an entry-sequenced Cnonindexed) cluster, D50.EXAMPLE.ESDS1. 
No password for the cluster is required, because the cluster was 
defined without passwords. 


//ALTERI JOB... 

“/STEPI EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

SASYSIN DD % 

ALTER - 

D50.EXAMPLE.ESDS1 - 
MASTERPNCDEPT26M) —- 
CONTROLPNCDEPT26C) - 
UPDATEPNCDEPT26U) - 
READPWCDEPT26R) —- 
AUTHORIZATIONC D26AUTH) 

7% 


The ALTER command adds passwords to the entry-sequenced 
cluster's cluster catalog entry. However, the passwords are not 
added to the cluster's data entry. If a user's program supplies 
the cluster's data entry entryname and opens the data component, 
the unauthorized user can access the cluster's data records even 
though the cluster itself is password-protected. 


The ALTER command's parameters are: 


° D50.EXAMPLE.ESDS]1, the name of the entry-~sequenced cluster. 
t* 1s assumed that an alias entrynamed D50 exists for the 
user catalog D27UCAT2. The data set name, 
D50.EXAMPLE.ESDS1, causes the ALTER request to be directed 
to D27UCAT2. 


e MASTERPW, CONTROLPW, UPDATEPW, READPW, and AUTHORIZATION, 
specify passwords and the entryname of the 
user~security-verification routine. 


Alter the Entrynames of Generically Named Clusters: Example 2 


In this example, several clusters with similar names, 
GENERIC.®.BAKER Cwhere "™*" is any 1- to 8-character simple 
name), are renamed so that their entrynames are GENERIC.X*.ABLE. 
The name "GENERIC.*.BAKER™ is called a generic name. 


//ALTER2 JOB ae 
//IQBCAT DD DSNAME=USERCATS, DISP=SHR 
//STEPI EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
77SVSIN DD % 
ALTER - 
GENERIC.®.BAKER - 
NEWNAMECGENERIC.*.ABLE) 
7X 


Job control language statement: 


e JOBCAT DD, which makes a catalog available for this job: 
USERCATS. 


The ALTER command changes each generic entryname, 
GENERIC.*.BAKER, to GENERIC.*.ABLE. Its parameters are: 


e GENERIC.®.BAKER, which identifies the objects to be 
modified. 


@ NEWNAME, which specifies that each generic entryname 
GENERIC.®.BAKER is changed to GENERIC.X.ABLE. 
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Alter the Attributes of a Generation Data Group: Example 3 


In this example, the attributes of a generation data group are ly ; 


modified. Because the attributes of the group are cataloged in Sr 


the generation data group's base catalog entry, only this entry 
is modified. | 


“7 ALTERS JOB ee 
//STEPI EXEC PGM=IDCAMS 
Z/SYSPRINT DD SYSOUT=A 
S/SYSIN DD * 
ALTER - 

GDGO1 - 

NOEMPTY —- 

SCRATCH 
/® 


The ALTER command modifies some of the attributes of generation 
data group GDGOl1. Its parameters are: 


e GDG01, which identifies the object to be modified. 


e NOEMPTY, which specifies that only the oldest generation 
data set is to be uncataloged when the maximum number of 
cataloged generation data sets is exceeded. 


® SCRATCH, which specifies that the generation data set's DSCB 
is to be removed from the volume's VTOC when the data set is 
uncataloged. | 


The attributes specified for the generation data group with the 


Anna lial override any attributes previously specified for 
e ‘ 
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The BLDINDEX command builds alternate indexes for existing data 


sets. 


The format of this command is: 


BLDINDEX| C{INFILE(ddnamel /password]) 


[ 
INDATASET (entrynamel “password }} 
{OUTFILE(ddnamel /password) 
e 


[~password)..-1)3 


[C entryname 
[EXTERNALSORT | INTERNALSORT] 
[WORKFILES(ddname ddname)1 
[CATALOG( catnamel/password])] 





BLDINDEX can be abbreviated: BIX 


BLDINDEX PARAMETERS 


Required Parameters 


a cities aia cei i i ai ss Sods Sabi debe ahi pts aera 


INFILE( ddnamel /password!]) | INDATASET(Centrynamel[/password 1) 
names the DD statement or data set that identifies the base 
cluster or a path that points to the base cluster. 


INFILE(ddnamel/pa 


password] ) 
specifies the DD statement that identifies the base 
cluster or a path that points to the base cluster. 
The base cluster must be defined in the same catalog 
as the alternate index, and must contain at least one 
data record. 


fe) 
If the base cluster or path is password 
protected, supply the read Cor higher-level) 
password of the object named in the DD statement. 
If you don't supply the password, the operator or 
TSO terminal user will be prompted to supply the 
correct password. RACF: The read or higher RACF 
authority of the object named in the DD statement 
1s required. 


Abbreviation: IFILE 


INDATASETCentrynamel/pa 


password, ; 
names the data set that identifies the base cluster or 
a path that points to the base cluster. The base 
cluster must be defined in the same catalog as the 
ac ee index, and must contain at least one data 
record. 


If the base cluster or path is password 
protected, you supply the read Cor higher-level) 
password of the named object. Otherwise, the 
operator or TSO terminal user will be prompted to 
supply the correct password. RACF: The read or 
higher RACF authority of the named objects is 
required. 


When you specify INDATASET, an attempt is made to 
dynamically allocate the base cluster's volume. 
Therefore, the base cluster's volume must be mounted 
as permanently resident or reserved. 


Abbreviation: IDS 
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Optional Parameters 





OUTFILE( ddnamel password] ) JOUTDATASET(entrynamel/ 


names the DD statement or data set that identities the ies 
alternate index or a path that points to the alternate Le 
index. You can build more than one alternate index for the ae 
same base cluster by specifying more than one ddname or 
data set name with the OUTFILE or OUTDATASET parameter. 


OUTFILE(ddnamel/password1[ ddnamel/password1]...1) 
specifies the DD statement that identifies the 
alternate index or a path that points to the alternate 
index. The alternate index must be defined in the 
same catalog as the base cluster, and must be empty 
Cthat is, its high-used RBA equals zero) or defined 
with the REUSE attribute. 


The alternate index must be related to the base 
cluster identified with INDATASET or INFILE. 


If the alternate index or path is password 
protected, supply the update- or higher-level 
password of the object named in the DD statement. 
If you don't supply the password, the operator or 
TSO terminal user will be prompted to supply the 
correct password. RACF: The update or higher 
RACF authority of the named object is required. 


Abbreviation: OFILE 
OUTDATASETlCentrynamel/password!] [entrynamel/password]...1) 


specifies the data set that identifies the alternate 
index or a path that points to the alternate index. 
The alternate index must be defined in the same 
catalog as the base cluster, and must be empty (that 
is, its high-used RBA equals zero) or must have been 
defined with the REUSE attribute. 


The alternate index must be related to the base Se 
cluster identified with INDATASET or INFILE. 


password 
If the alternate index or path is password 
protected, you supply the update- or higher-level 
password of the named object. Otherwise, the 
operator or TSO terminal user may be prompted to 
supply the correct password. RACF: The update or 
higher RACF authority for the named object 15s 
required. 


When you specify OUTDATASET, an attempt is made to 
dynamically allocate the alternate index's volume. 
Therefore, the volume must be mounted as permanently 
resident or reserved. 


Abbreviation: ODS 


CATALOG( catnamel /password]) 


names the catalog that the work files are to be defined in. 
eo files are defined and used by the BLDINDEX 
routine. 


When all alternate indexes are built and the work files are 
no longer needed by the BLDINDEX routine, they are deleted. 


N uA 


4 oe 
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ae. If the catalog is password protected, supply its 
( update- or higher-level password. If you don't supply 
the password, the operator will be prompted to supply 
the correct password. RACF: The update or higher RACF 
authority to the catalog is required. 


For information about the order in which a catalog is 
selected when the CATALOG parameter is not specified, see 
"Order of Catalog Selection for BLDINDEX™ on page 15 


Abbreviation: CAT 


EXTERNALSORT | INTERNALSORT 
specifies whether the key-pointer pairs are to be sorted 
entirely within virtual storage. 


EXTERNALSORT 
specifies that two external sort work files will be 
defined and built as entry-~sequenced clusters. You 
must provide two DD statements that describe the 
external sort work files to be defined by BLDINDEX. 


You can name the DD statements IDCUT1 and IDCUT2. 

When you choose other names for the work file DD 
statements, you must identify those DD statements with 
the WORKFILES parameter. 


INTERNALSORT 
specifies that access method services will sort the 
key-pointer pairs entirely within the user-provided 
virtual storage if possible. 


If not enough virtual storage is provided when you 
specify INTERNALSORT, two external sort work files are 


Bs built and the key-pointer pairs are sorted externally. 
( In this case, you must provide DD statements as for 
EXTERNALSORT. 


If the minimum amount of virtual storage is not 
provided (see VSAM Administration Guide), the BLDINDEX 
processing terminates with an error message. 


Abbreviations: ESORT and ISORT 


WORKFILES(ddname ddname ) 
names the DD statements that identify the work files you 
want BLDINDEX to define if an external sort of the 
key~pointer pairs is required. 


You can use DD statements to describe two work files that 
will be defined and opened before the BLDINDEX routine 
begins processing the base cluster's data records. 


When you code the DD statements that describe the work 
files and identify them with the standard ddnames, IDCUT1] 
and IDCUT2, you do not need to specify the WORKFILES 
parameter. 


For information on how to code the DD statements that 
describe the work files, see "DD Statements that Describe 
the SORT Workfiles™ in ini j j : 


Abbreviation: WFILE 
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BLDINDEX 
BLDINDEX EXAMPLE 


Build an Alternate Index Over a Key-Sequenced Data Set: Example 1 


This example builds an alternate index over a previously defined 
base cluster, EXAMPLE.KSDS2. Data records have already been 
loaded into the base cluster, so that it is not empty. The 
alternate index, its path, and its base cluster are all defined 
in the same catalog, USERRCAT. 


//BUILDAIX JOB... 

Z/STEPCAT DD DSNAME=USERRCAT, DISP=SHR 

//BASEDD DD DSNAME=EXAMPLE.KSDS2, DISP=OLD 

4/KIXDD DD DSNAME=EXAMPLE.AIX, DISP=OLD 

//TDCUT1 DD DSNAME=SORT.WORK. ONE, DISP=OLD,AMP="AMORG', 

17 VOL=SER=VSERO1,UNIT=DISK 

//TDCUT2 DD DSNAME=SORT.WORK. TWO, DISP=OLD,AMP="AMORG', 

// VOL=SER=VSERO1,UNIT=DISK 

//SYSPRINT DD SYSOUT=A 

S/SYSIN DD xX 

BLDINDEX INFILECBASEDD) —- 
OUTFILECAIXDD/AIXUPPW) - 
CATALOGCUSERRCAT/USER) 

7% 


Job control language statements: 

e STEPCAT DD, which describes the catalog. 

e BASEDD DD, which describes the base cluster. 

e AIXDD DD, which describes the alternate index. 


e IDCUT1 and IDCUT2 DD, which describe a volume containing 
VSAM data space to be made available to BLDINDEX for 
defining and using two sort work data sets in the event an 
external sort is performed. This data space will not be 
used by BLDINDEX if enough virtual storage is available to 
perform an internal sort. If multiple volumes are involved, 
a maximum of five volumes for each work file can be 
specified. 


The BLDINDEX command builds an alternate index. The assumption 
is made that enough virtual storage will be available to perform 
an internal sort. However, note that DD statements with the 
default ddnames of IDCUT1] and IDCUT2 have been provided for two 
external sort work data sets in the event that the assumption is 
incorrect and an external sort must be performed. 


The BL DINDEX command's parameters are: 


® INFILE, which names the base cluster. The ddname of the DD 
statement for this object must be identical to this name. 
Note that a password is not required, because the base 
cluster is not protected. 


e OUTFILE, which names the alternate index. The ddname of the 
DD statement for this object must be identical to this name. 
The update password of the alternate index is also required. 


e CATALOG, which identifies the user catalog. If it is 
necessary for BLDINDEX to use external sort work data sets, 
they will be defined in and deleted from the catalog. The 
update password will permit these actions. 
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CHKLIST 


( | The CHKLIST command lists tape data sets that were opened during 
a a checkpoint. The format of this command is: 


CHKLIST INFILE(ddname) 
[CHECKID( checkid...)] 
COUTFILE(ddname)1 


CHKLIST can be abbreviated: CKLST 





CHKLIST PARAMETERS 


Required Parameter 
INFILE(ddname} 


specifies the name of the DD statement that identifies the 
checkpoint data set that contains the checkpoint entries to 
be processed. 


Abbreviation: IFILE 


Optional Parameters 
CHECKID( checkid... ) 


specifies one or more checkpoint identifiers of entries in 
the checkpoint data set. These entries contain names of 
tape data sets that were open at the time of the 
checkpoint. 


checkid must be 1 to 16 characters in length. 


The checkid must be the same as was specified in the 
CHKPT macro. A maximum of 255 checkids can be 
specified. Multiple checkids may be specified in any 
sequence. 


If the checkpoint data set contains duplicates of a 
checkid, you can cause all the checkpoint entries with 
that checkid to be listed: 


e By specifying the checkid at least twice 


@ By specifying, along with the checkid, a checkid 
oA which there is no entry in the checkpoint data 
se 


If you do neither, only the first checkpoint entry 
found with the checkid is listed. 


If CHECKID is omitted, the identifications of tape data 
sets that were open at the time of a checkpoint are listed 
for all entries in the checkpoint data set. 


CHECKID must be omitted when a member of a partitioned 
checkpoint data set has been specified after ddname in the 
DD statement identified by INFILE. 


Abbreviation: CHKID 
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CHKLIST 


OUTFILE(ddname) 
specifies the ddname of the DD statement that identivies a oo. 
data set other than the SYSPRINT data set to be used as a ie 3 
target data set. & 
A target data set must meet the requirements shown under _ 
"For a Target Data Set™ on page 10. If OUTFILE is not 
specified, the tape data set information is listed in the 
SYSPRINT data set. 
Abbreviation: OFILE 
J Ea | 
= 
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CHKLIST 


Selecting Specific Checkpoint Entries: Example 1 


Processing a Member 


In this example, the tape data sets that were open at checkpoint 
time are identified and listed on SYSPRINT for checkpoint 
entries C0000001 and C0000002. 


//CHKLIST1 JOB 


//STEPI EXEC PGM=IDCAMS 
“/SYSPRINT DD SYSOUT=A 
Z/CHKPT ~~ ODD DSN=CHKPT . DATASET, DISP=OLD 
S/SSYSIN DD % 
CHKLIST - 
INFILECCHKPT) - 


CHECKIDCC0000001 CO000002) 
7% 


Job control statement: 


® CHKPT DD, which identifies the checkpoint data set that 
contains the entries for which the tape data set information 
is to be listed. 


The CHKLIST command prints the tape data set information as 
specified by the command's parameters: 


@ INFILE, which points to the CHKPT DD statement. The CHKPT 
DD statement identifies the checkpoint data set. 


e CHECKID, which specifies that the checkpoint entries with 
checkids C0000001 and C0000002 are the only ones on the 
checkpoint data set for which the tape data set information 
1s to be listed. 


The output shown in Appendix C, "Sample Output from CHKLIST®™ on 
page 315 was obtained with this JCL. 


of a Partitioned Checkpoint Data Set: Example 2 


In this example, the checkpoint data set is a partitioned data 
set, and member C0000001 is selected for processing by CHKLIST. 


//CHKLIST2 JOB oes 

//STEP1 EXEC PGM=IDCAMS 

Z/SYSPRINT DD SYSOUT=A 

//CHKPTDD DD DSN=EXAMPLE.CHKPTDS2¢(C0000001), 


// DISP=SHR | 
S/SYSIN DD X 
CHKLIST - 
INFILECCHKPTDD) 
7% 


Job control language statement: 


e CHKPTDD DD, which identifies the partitioned checkpoint data 
set and the specific member for which the tape data set 
information is to be listed. 


The CHKLIST command prints the tape data set information as 
specified by its parameter, INFILE, which points to the CHKPTDD 
DD statement. The CHKPTDD DD statement identifies the member of 
the partitioned checkpoint data set. 


The CHECKID parameter is omitted, so the checkpoint entry 
CO000001 will automatically be processed by CHKLIST. 
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CNVTCAT 


CNVTCAT 


The CNVTCAT command converts OS CVOL entries into VSAM catalog 
entries. The format of this command is: 








CNVTCAT | fINFILE(ddname) | 
INDATASET ( 


CATALOG ( 
[CVOLEGUATES{ (catnane oe 
volser...-JJ)JE (catname...)...1)] 
[LI EST THOLEST Tl. 
[MASTERCATALOG(catnamel/password])1 





| CNVTCAT can be abbreviated: CNVTC 


| CNVTCAT PARAMETERS 


Required Parameters 
INFILE( ddname) | INDATASETlCentryname) 


specifies the name of a DD statement or an alias entryname 
for an OS CVOL to be converted to a VSAM catalog. 


INFILE( ddname) 
specifies the name of a DD statement for an OS CVOL 
that is to be converted. 


wo ~ 


specifies the name of the DD statement that identifies \ 
the 0S CVOL that is to be converted. ol 


| Abbreviation: IFILE 
INDATASET Centryname/password) 


specifies the alias entryname Cin the master catalog) 
of the OS CVOL that is to be converted. 


If INDATASET is specified, an attempt is made to 
dynamically allocate the OS CVOL. The OS system 
catalog entryname, SYSCTLG, cannot be specified. 


Abbreviation: IDS 


m 
names the entry to be converted. 


mate cae Seance aces 
identifies the VSAM catalog to receive the converted 0S 
CVOL entries. 


OUTFILE(ddnamel /password] ) 


specifies the name of a DD statement that identifies 
the target VSAM catalog. 


identifies the VSAM target catalog. 


specifies the update- or higher-level password for a 
password-protected catalog. RACF: The update or 
higher RACF authority to the catalog is required. 


Abbreviation: OFILE \ 
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CNVTCAT 


OUTDATASET Centrynamel /password1]) 
specifies the name of the VSAM target catalog. If 


OUTDATASET is specified, an attempt is made to 
dynamically allocate the catalog. 


names the target VSAM catalog. The alias name of the 
catalog will not be accepted. 


specifies the update- or higher-level password for a 
password protected catalog. RACF: The update or 
higher RACF authority to the catalog is required. 


Abbreviation: ODS 
CATALOG( catnamel /password] ) 


specifies the name of a catalog that is to receive the 
converted entries. The alias name of the catalog will 
not be accepted. 


specifies the update- or higher-level password for a 
password-protected catalog. RACF: The update or 
higher RACF authority for the catalog is required. 


Abbreviation: CAT 


Optional Parameters 
CVOLEQUATES( (catname (volserl volser...JIJIL (catname...)] 


identifies the user catalog that converted control volume 
pointer entries (CVPEs) point to. 


CVPEs point to OS CVOLs that contain entries. The entries 
in an OS CVOL might have been Cor might soon be) converted 
to VSAM catalog entries. 


When a CVPE is converted to an alias entry, the alias entry 
points to the user catalog that contains Cor is to contain) 
the OS CVOLS converted entries. 


When you specify CVOLEQUATES, you must also specify 
MASTERCATALOG. 


specifies the name of an existing VSAM catalog. The 
catalog named contains or is to contain converted OS 
CVOL entries that were cataloged in the OS CVOL 
pointed to by the CVPE being converted. 


volser 
specifies the volume serial number(s) of one or more 
OS CVOLs for which entries have been or are to be 
converted. 


Abbreviation: CVEQU 


LIST{[NOLIST 
specifies whether entries are to be listed. 


LIST 
specifies that entries are to be listed after they are 
converted. 


NOLIST 
specifies that entries are not to be listed after they 
are converted. 


Abbreviation: NLIST 
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CNVTCAT 


CNVTCAT EXAMPLES 





MASTERCATALOG(catnamel[/ ) | 
specifies the name of the master catalog into which any po 
aliases for user catalogs are to be placed. MASTERCATALOG te | 
is required when CVOLEQUATES is specified. Qo 
Password | 
specifies the master catalog's update- or higher-level 
password. 


Abbreviation: MCAT 


The two CNVTCAT examples are related and show how the entries of 
two OS CVOLsS in a system can be converted to entries ina 
catalog. The OS CVOL on volume VSERO9 contains control volume 
pointer entries (CVPEs) that point to the OS CVOL on volume 
VSERO&8. Therefore, the two OS CVOLsS are chained together with 
VSERO8's OS CVOL at the end of the chain. When two or more OS 
CVOLs are chained together, the OS CVOL at the end of the chain 
should be converted first. 


Convert OS CVOL Entries to Entries in a VSAM Catalog: Example 1 


In this example, the entries in the 0S CVOL on volume VSERO8 are 
eons to catalog entries and written into the USERI]11 
catalog 


//CNVTCAT1 JOB ; 

//STEPI EXEC PGM=IDCAMS 

Z/SYSPRINT DD SYSOUT=A 

//OSCATI DD VOL=SER=VSER08, DISP=OLD, DSN=SYSCTLG, 
7 UNIT=DISK 


//SYSIN DD =X gk 
CNVTCAT - -_ 
INFILECOSCAT1) - — 
CATALOGCUSER11/MR) . 
7% 


Job control language statement: 


e OSCAT1 DD, which describes and allocates the 0S CVOL that is 
to be converted. 


The CNVTCAT command converts the entries in the OS CVOL on 
volume VSERO8 to entries ina user catalog, USERI11. The 
command's parameters are: 


e INFILE, which points to the OSCAT1 DD statement. 


® CATALOG, which specifies the name of an existing catalog, 
the user catalog USERI1. USERI11 is to receive the converted 
entries. The user catalog’s update~ or higher-level 
password, MR, is required if passwords are used. 
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CNVTCAT 
Convert an OS CVOL Having Control Volume Pointer Entries: Example 2 


( In this example, the entries in the OS CVOL on volume VSERO9 are 

b.. converted to catalog entries and written into the USER12 
catalog. Some of the entries in the OS CVOL are control volume 
pointer entries, and point to the OS CVOL on volume VSERO8 
Cwhich was converted in the previous example). 


S/CNVTCAT2 JOB rae 
//STEPIL EXEC PGM=IDCAMS 
“/7SYSPRINT DD SYSOUT=A 
//OSCAT2 DD VOL=SER=VSERO9, DISP=OLD, DSN=SYSCTLG, 
// UNIT=DISK 
7/SYSIN DD xX 
CNVTCAT - 
INFILECOSCAT2) - 
CATALOGCUSERI2/MR) - 
CVOLEQUATESC - 
CUSERI1 CVSERO8)) ) os 
NOLIST - 
MASTERCATALOGCAMASTCAT )D 
7% 


Job control language statement: 


6 OSCAT2 DD, which describes and allocates the OS CVOL that is 
to be converted. 


The CNVTCAT command converts the entries in the OS CVOL on 
volume VSEROI to entries ina user catalog, USERI12. Because 
CVOLEQUATES is specified, an alias entry is built and put in the 
master catalog to relate the name VSERO08 to the user catalog 
USER11. The command's parameters are: 


e INFILE, which points to the OSCAT2 DD statement. 


( @ CATALOG, which specifies the name of an existing catalog, 

| the user catalog USER12. USER12 is to receive the converted 
entries. The user catalog's update- or higher-level 
password, MR, is required if passwords are used. 


e CVOLEQUATES, which specifies that control volume pointer 
entries (CVPEs) are to be converted to alias entries. Each 
CVPE in VSERO9's OS CVOL points to an entry in VSERO8's OS 
CVOL. Each new alias entry points to the USERI1 user 
catalog connector entry in the master catalog. The alias 
entries are written into the master catalog. 


e NOLIST, which specifies that the entries are not to be 
listed after they are converted. 


® MASTERCATALOG, which identifies the master catalog. This 
parameter must be specified because CVOLEQUATES is also 
specified. If the master catalog is password-protected, the 
catalog's update- or higher-level password must be 
specified. 
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DEFINE ALIAS 
DEFINE ALIAS 


The DEFINE ALIAS command defines an alternate name for a —— 
non-VSAM data set or a user catalog. The format of this command we 
is: | 


ALTAS | 
(NAME Caliasname) 


RELATE lentryname)) , 
[CATALOG( catnamel/password] J] 





DEFINE can be abbreviated: DEF 


DEFINE ALIAS PARAMETERS 


Required Parameters 


Optional Parameter 


ALIAS 
specifies that an alias for a user catalog or non-VSAM data 
set is to be defined. 


NAME (aliasname) 
specifies the alias (the alternate entryname) for a user 
catalog or non-VSAM data set. An alias must be unique 
within a catalog. 


RELATE (entryname } 
specifies the name of the entry (the user catalog entryname 
oe err onn data set name) for which the alias is being 
efined. 


An alias entry must reside in the same catalog as the entry 
to which it is related. When an alias is defined, catalogs 
are searched for the related entry. When the related entry 
is found, the alias entry is added to the catalog. 


Abbreviation: REL 


CATALOG( catnamelZ 3) 
identifies the catalog in which the alias is to be defined. 


If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. For information about 
the order in which a catalog is selected when the catalog's 
name is not specified, see "Order of Catalog Selection for 
DEFINE™ on page 16 


specifies the name of the catalog. When the alias is 
for a user catalog connector, catname is the name of 
the master catalog. 


specifies a password. If the catalog is password 
protected, supply the catalog'’s update- or 
higher-level password. If you don't supply the 
password, the operator or TSO terminal user will be 
prompted to supply the correct password. RACF: The 
update or higher RACF authority to the catalog is 
required. 


Abbreviation: CAT a 
Xe, o a 
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DEFINE ALIAS 
DEFINE ALIAS EXAMPLES 





Define an Alias for a Non-VSAM Data Set: Example 1 
In this example, an alias is defined for a non-VSAM data set. 


//DEFALS JOB «te 
//STEPI EXEC PGM=IDCAMS 


//STEPCAT DD DSNAME=USERCAT4, DISP=OLD 
//SY¥SPRINT DD SYSOUT=A 
//SYSIN DD X 


DEFINE ALIAS - 
CNAMECEXAMPLE.NONVSAMI) - 
RELATECEXAMPLE.NONVSAM) ) - 
CATALOGCUSERCAT 4/7 USERMRPHW) 

7% 


Job control language statement: 


e STEPCAT DD, which makes a catalog available for this job 
step: USERCATS. 


The DEFINE ALIAS command defines an alias, EXAMPLE.NONVSAMIL, for 
the non-VSAM data set EXAMPLE.NONVSAM. Its parameters are: 


e NAME, which specifies the alias Calternate entryname), 
EXAMPLE.NONVSAM1. 


e RELATE, which specifies the name that the alias is an 
alternate entryname for, EXAMPLE.NONVSAM. 


| | e CATALOG, which supplies the update password of the user 
! catalog. 
( Define an Alias for a User Catalog: Example 2 


In this example, an alias is defined for a user catalog. The 
alias is defined in the master catalog. 


//DEFUCALS JOB 


//STEPI EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
S/SYSIN DD X 
DEFINE ALIAS - 
CNAMECD40) - 
RELATECD27UCAT1)) - 


CATALOGCAMAST1/MASTUPNHI 3 
/% 


The DEFINE ALIAS command defines an alias, D460, for the user 
catalog, D27UCAT1. Any data set defined in D27UCATI having 

'DG0"' as its first qualifier will be located by VSAM in D27UCATI 
when it is referred to in an access method services command or 
user program without requiring a JOBCAT or STEPCAT DD statement 
for D27UCAT1. D27UCAT1 can also be referred to using the alias 
DG0. The parameters are: 


e NAME, which specifies the alias, D40. 


e RELATE, which specifies the name of the user catalog for 
which DG0 is an alternate entryname Calias). 


° CATALOG, which supplies the update password of the master 
catalog. 
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DEFINE ALTERNATEINDEX 
DEFINE ALTERNATEINDEX 


The DEFINE ALTERNATEINDEX command defines an alternate index. 
When you use this command, you can specify attributes for the 
alternate index as a whole and for the components of the 
cesar index. The format of the DEFINE ALTERNATEINDEX 
command is: 


DEFINE ALTERNATEINDEX Cparameters) - 
| [DATACparameters)] - 
LINDEX( parameters) ] - 
[CATALOG(subparameters) ] 


ALTERNATEINDEX 
(NAME ( 
RELATE ( 


VOLUMES ( [ 

[ATTEMPTS (number [2)] 
[AUTHORIZATION(entrypointl( stringi)] 
[BUFFERSPACE(size)]1 

[CODE(code)] 

CONNORS oe cee eae paeeees 
[CONTROLPW(password)1 

IDESTAGEWATT INODESTAGEWAIT: 

ERASE | NOERASE]J 

LEXCEPTIONEXIT (entrvpoint)} 
[FILE(ddname)] 

PF REESPAce (cl—percent| CA-percent]!19Q 0)] 
[IMBED | NOIMBED] 

[KEYRANGES ( (lowkey hiahkey) 
C(lowkey highkey)...1])] 
[KEYS(lenath offset |o4 9)] 

MAS TERPW( password) ] 

EMODEL Centrypamel /password] 
[ catnamel spassword]1)1 

fORDERED | UNORDERED | 

[COWNER(ownerid)] 

[READPW( password)] 

[RECORDSIZElaverage maximum| 
086 32 )] 

PREP LICATE INQREPLICATE) 

[REUSE [NOREUSE] 

[SHAREOPTIONS(crossregion 

cr rosssvetemt Id 3)] 

[SPEED | ] 

(STAGE BEND (CULINDERFAULT2 

[TOC date) | FOR( days) ] 

[UNIQUE | SUBALLOCATION] 


TUNTQUEKEY | NONUNIQUEKEY' 
LUPDATEPW( 


password) 
[UPGRADE | NOUPGRADE] 
[WRITECHECK | NOWRITECHECK] ) 





CContinued on next page.) 
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DEFINE ALTERNATEINDEX 


[DATA 

( LATTEMPTS (number )] 
[AUTHORIZATION(entrypoint£ string])] 
[BUFFERSPACE(size)] 
[CODE(code)] 
[CONTROLINTERVALSIZE(size)] 
[CONTROLPW( password) ] 
[CYLINDERS (primarvl 

RECORDS (primaryvl 

TRACKS ( 1 [ 
[ DESTAGEWAIT | NODESTAGEWAIT] 
[ERASE | NOERASE] 
PEXCEP TONEXTT Centrypoint)1 
[FILE(ddname)] 
[FREESPACE(CI-percentl €A-percent1)3 
C[KEYRANGES( ( lowkey 

[Clowkey highkey)...1])] 
[KEYS(length offset)! 
PAS TERPW i password) 1 
[MODEL Centrynamel /password] 
CRANE eet “password! 1) ] 


entryname} 
biti tt pea eee a 
[OWNER(ownerid)] 
[READPW(password)] 
C[RECORDSIZElaverage maximum)] 
[REUSE |NOREUSE] 
[SHAREOPTIONS(crossregiont crosssystem1)]1 
[SPEED] RECOVERY] 
[STAGE |BIND|CYLINDERFAULT] 
CUNIQUE | SUBALLOCATION] 
[UNIQUEKEY | NONUNIQUEKEY] 
[UPDATEPW (password) ] 
[VOLUMES(volserf volser... 
[WRITECHECK | NOWRITECHECK] )] 





1)] 


[INDEX 
CLATTEMPTS (number J] 
[AUTHORIZATION(C entryvpointl 
[CODE(code)] 
[CONTROLINTERVALSIZE(size)1 
[CONTROLPW( password) ] 
[CYLINDERS (primaryl 
RECORDS (primaryl 
TRACKS (primaryl eco 
[DESTAGEWAIT | NODESTAGEWAITI 
LEXCEPTIONEXITlentrypoint)] 
[FILE(ddname)] 
[IMBED|NOIMBED] 
[MASTERPW( password) ] 
[MODEL Centrynamel/password] 
[ catnanel /password!1)1 
[NAME le 
| ORDERERTUNGEDERED: 
COWNER(ownerid)1 
[READPW( password)] 
[REPLICATE | NOREPLICATE] 
[REUSE |NOREUSE] 
CSHAREOPTIONS(crossregion£t crosssystem])]1 
[STAGE |BIND| CYLINDERFAULT] 
shyt oa dane lane 
[UPDATEPW(password)] 
[VOLUMES(volser[f volser...]J])] 
[WRITECHECK I NOWRITECHECK) } J 


[CATALOG( catname! /password])] 





DEFINE can be abbreviated: DEF 
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DEFINE ALTERNATEINDEX 
DEFINE ALTERNATEINDEX PARAMETERS 


Required Parameters 
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ALTERNATEINDEX 


specifies that an alternate index is to be defined. 


The ALTERNATEINDEX keyword is followed by the parameters 
specified for the alternate index as a whole. These 
parameters are enclosed in parentheses and, optionally, are 
followed by parameters specified separately for the DATA 
and INDEX components. 


Abbreviation: AIX 


NAME (entryname) 


specifies the alternate index's entryname or the name of 
each of its components. The entryname specified for the 
alternate index as a whole is not propagated to the 
alternate index's components. 


You can define a separate entryname for the alternate 
index, its data component, and its index component. If no 
name is specified for the data or index component, a name 
is generated. 7 


When the alternate index, data component, and index 
component are individually named, each can be addressed. 


RELATE Centrynamel/password] ) 


names the alternate index's base cluster. The base cluster 
is an entry~sequenced cluster or a Key~sequenced cluster 
that the alternate index is to be related to. You cannot 
relate an alternate index to a reusable cluster or a 
relative record cluster. 


password 
specifies either the base cluster's master password or 
the catalog's master password (that is, the master 
password of the catalog that contains the base 
cluster's entry). 


If no password is specified with either the RELATE or 
the CATALOG parameter, VSAM will ask the operator for 
the base cluster's master password. RACF: The alter 
RACF authority to the base cluster or catalog is 
required. 


Abbreviation: REL 


CYLINDERS(primaryl[ secondary!) | 


RECORDS(primaryl secondary])| 
TRACKS(primarvl secondary] )} 


specifies the amount of space to be allocated to the 
alternate index from the volume’s available space when 
UNIQUE is specified, or from the available space of one of 
the volume's VSAM data spaces. 


Unless you specify the MODEL parameter, you must specify 
one, and only one, of the following parameters: CYLINDERS, 
RECORDS, or TRACKS. 


When you specify UNIQUE, space is always allocated in 
cylinders. If the amount of space you specify for the data 
component of the alternate index is not an even multiple of 
cylinder size, VSAM rounds the allocation upward to a 
multiple of a cylinder. 


If you specify RECORDS, the amount of space allocated is 


the minimum number of tracks that are required to contain 
the specified number of records. However, if you specify 
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DEFINE ALTERNATEINDEX 


TRACKS or RECORDS and the minimum number of tracks exceeds 
a cylinder, space is allocated in terms of cylinders. 


When UNIQUE or REUSE is specified, each volume can contain 
a maximum of 16 extents. 


When the data component is not divided into key ranges and 
more than one volume is specified, the primary amount of 
space is allocated only on the first volume when the 
component is defined. When the component increases in size 
so as to extend on to additional volumes, the first 
allocation on each overflow volume is the primary amount. 


When KEYRANGES is specified and the data component is to be 
contained on more than one volume, the primary amount of 
space 1s immediately allocated on each volume required for 
the key ranges. If more than one key range is allocated on 
a single volume, the primary amount is allocated for each 
key range. 


Secondary amounts can be allocated on all volumes available 
to contain parts of the alternate index regardless of the 
key ranges when the alternate index is extended. 


You can specify the amount of space as a parameter of 
ALTERNATEINDEX, as a parameter of DATA, or as a parameter 
of both DATA and INDEX. If the space is specified as a 
parameter of: 


® ALTERNATEINDEX, the amount specified is divided between 
the data and index components. The division algorithm 
is a function of control interval size, record size, 
device type, and other data set attributes. 


If the division results in an allocation for the data 
component that is not an integral multiple of the 
required control area size, the data component's 
allocation is rounded up to the next higher control 
area multiple. This rounding may result ina larger 
total allocation for your alternate index than that 
which you specified. 


° DATA, the entire amount specified is allocated to the 
data component. An additional amount of space, 
depending on control interval size, record size, device 
type, and other data set attributes, is allocated to 
the index component. 


To determine the exact amount of space allocated to each 
component, list the alternate index's catalog entry, using 
the LISTCAT command. 


When you specify UNIQUE and the alternate index's data 
space is the first data space on a volume that belongs to a 
recoverable catalog, one additional cylinder is allocated 
for the catalog recovery area. 


The primary and each secondary allocation must be able to 
be satisfied within five extents; otherwise, your DEFINE or 
data set extension will fail. Primary and secondary can be 
expressed in decimal (€n), hexadecimal (X'n"), or binary 
CBin') form. 


specifies the initial amount of space that is to be 
allocated to the alternate index. 


secondary 
specifies the amount of space that is to be allocated 
each time the alternate index extends, as a secondary 
extent. When secondary is specified and the alternate 
index is suballocated, space for the alternate index's 
data and index components can be expanded to include a 
maximum of 123 extents. 
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If the data space that contains all or part of the 
cluster cannot be extended because the cluster's 
secondary allocation amount is greater than the data 
space's secondary allocation amount, VSAM builds a new 
data space. The new data space's primary and 
secondary allocation amounts are equal to the 
cluster's secondary allocation amount. 


Abbreviations: CYL, REC, and TRK 


VOLUMES(volserl volser...1) 


specifies the volume(s) on which an alternate index's 
components are to have space. 


If you do not specify the MODEL parameter, VOLUMES must be 
specified either as a parameter of ALTERNATEINDEX, or as a 
parameter of both DATA and INDEX. 


If the data and index components are to reside on different 
device types, you must specify VOLUMES as a parameter of 
both DATA and INDEX. If more than one volume is listed 
with a single VOLUMES parameter, the volumes must be of the 
same device type. 


A volume serial number may be repeated in the list only if 
the KEYRANGE parameter is specified. You may want to do 
this in order to have more than one key range on the same 
volume. Even in this case, repetition is only valid if all 
duplicate occurrences are used for the primary allocation 
of some key range. 


In a system with the Mass Storage System, an alternate 
index or component can be defined on a mass storage volume. 


The VOLUMES parameter interacts with other DEFINE 
ALTERNATEINDEX parameters. You should ensure that the 
volume(s) you specify for the alternate index are 
consistent with the alternate index's other attributes: 


e SUBALLOCATION: If UNIQUE is not specified, the volume 
must already contain VSAM data space. 


e KEYRANGES: If KEYRANGES and UNIQUE are specified for a 
VSAM catalog, a VSAM data space is built and allocated 
on a separate volume for each key range. 


° ORDERED: If ORDERED is specified, the volumes are used 
in the order listed. If ORDERED and KEYRANGES are 
specified, there is a one-to-one correspondence between 
the key ranges in the key range list and the volumes in 
the volser list. 


@ CYLINDERS, RECORDS, TRACKS: The volume(s) contains 
enough available space to satisfy the component's 
primary space requirement. 


° FILE: The volume information supplied with the DD 
statement pointed to by FILE must be consistent with 
the information specified for the alternate index and 
its components. 


@ CATALOG: The data space on the volume must be defined 
before the alternate index, and the catalog specified 
must own the volume. 


Abbreviation: VOL 
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Optional Parameters | 


ATTEMPTS (number 12) 
specifies the maximum number of times the operator can try 
to enter a correct password in response to a prompting 
message. 





This parameter only has effect when the alternate index's 
master password is not null. A prompting message is issued 
only when the user has not already supplied the appropriate 
password. 


number ; . 
is an integer from 0 to 7 and can be expressed in 
occas (nd, hexadecimal (X'n'), or binary CB*n') 

orm. 


When ATTEMPTS(CO) is coded, the operator is not 
prompted and is not allowed to enter a password from 
the console. 


Note to TSO users: At a TSO terminal, the logon 
password is checked first, before the user is prompted 
to supply a password for the alternate index. 

Checking the logon password counts as one attempt to 
obtain a password. If ATTEMPTS is not specified, the 
user has one attempt to supply the alternate index's 
password, because the default is 2 


Abbreviation: ATT 
AUTHORIZATION(entrypoint£ strinal) 


specifies that a user-~security-verification routine CUSVR) 
1s available for additional security verification. When a 
protected alternate index is opened and the user supplies a 


es, correct password other than the alternate index's master 
( iar tae the USVR receives control. For details on coding 
a » See ° 


If a USVR is loaded from an unauthorized library during_ 

access method services processing, an abnormal termination 

will occur. See "Authorized Program Facility™ in 
dministrati j : 


This parameter only has effect when the master password is 
not null. 


specifies the name of the USVR. 


specifies information to be passed to the USVR when it 
receives control to verify authorization. 


Abbreviation: AUTH 


BUFFERSPACE(size) 
specifies the minimum space that your program's address 
space is to provide for buffers. 


When you specify BUFFERSPACE, you must specify at least 
enough space to contain two data control intervals and one 
index control interval. The buffer space size you specify 
helps VSAM determine the data component's and index 
component's control interval size. If the specified size 
is less than VSAM requires for the buffers needed to run 
your job, VSAM terminates your job and provides an 
appropriate error message. 


When you do not specify BUFFERSPACE, VSAM determines the 
buffer space size. VSAM determines the control interval 
size first, then sets the buffer space amount equal to two 
data control intervals and one index control interval. 
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is the amount of space to be provided for buffers. 
The value can be expressed in decimal (n), hexadecimal 
CX n'), or binary CB'n') form, but must not exceed 


16776704. 
Abbreviations: BUFSPC or BUFSP 
CATALOG( catnamel /password]) 


identifies the catalog in which the alternate index is to 
be defined. The catalog also contains the base cluster's 
entry (see the RELATE parameter above). For information 
about the order in which a catalog is selected if the 
catalog's name is not specified, see "Order of Catalog 
Selection for DEFINE" on page 16 


specifies the catalog's name. 


specifies the catalog's update- or higher-level 
password. If the catalog is password-protected, you 
must supply the catalog's update- or higher-level 
password. If no password is specified with the 
CATALOG parameter, VSAM will prompt the operator for 
the catalog's update password. RACF: The update or 
higher RACF authority to the catalog is required. 


If the base cluster's master password is not specified 
with the RELATE parameter, the catalog's master 
password must be specified. RACF: The alter RACF 
authority to the catalog is required. 


If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. 


Abbreviation: CAT 
CODE(code) 


specifies a code name for the alternate index. If an 
attempt is made to access a password-protected alternate 
index without first supplying an appropriate password, a 
prompting message will be issued to the operator's console 
(see ATTEMPTS above). The prompting message includes the 
code name, which identifies the alternate index without 
revealing its entryname. 


This parameter only has effect when the alternate index's 
master password is not null. 


If you do not specify a code name for the alternate index, 
the prompting message identifies the alternate index with 
its entryname. 


CONTROLINTERVALSIZE(size) 
specifies the size of the alternate index's control 
intervals. The size of the control interval depends on the 
maximum size of data records, and on the amount of buffer 
space specified. 


When you do not specify the control interval size, VSAM 
determines the control interval size. If you have not 
specified BUFFERSPACE and the size of your records permits, 
VSAM selects the optimum size for the data control interval 
size and 512 bytes for the index control interval size. 


size ; 
for the alternate index's data component. 
Because an alternate index always has the spanned 


attribute, the control interval size can be less than 
the maximum record length. The sizes you can specify 
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(between 512 and 32 768 bytes) are integer multiples 
of 512 or 2048: 


CISZ = (n x 512) or (n x 2048) 
where nis a positive integer from 1 to 16. 


When you specify a size that is not a multiple of 512 
or 2048, VSAM chooses the next higher multiple. 


for the alternate index's index component. 


You can specify the following values for the index 
component's control interval size: 


CISZ = [512 | 1024 | 2048 | 4096] 


For a discussion of the relationship between control 
interval size and physical block size, refer to "Optimizing 
VSAM Performance”™ in V t fe) h 
discussion also includes restrictions that apply to control 
interval size and physical block size. 


Abbreviations: CISZ or CNVSZ 
CONTROLPW( password) 


specifies a control password for the entry being defined. 


When specified as a parameter of DATA or INDEX, the control 
password allows the user's program to open the data 
component or index component for read and write processing 
of the component's control intervals (that is, the entire 
control interval, including the data portion of stored 
records and the control fields VSAM inserts into stored 
records and control intervals). 


If a read or update password is the only password specified 
for the object, it (the highest-level password) propagates 
meee’ and becomes the password for all higher unspecified 
evels. 


Abbreviation: CTLPW 
DESTAGEWATT | NODESTAGEWAIT 


specifies whether an alternate index or its component that 
1s stored ona mass storage volume is to be destaged 
synchronously or asynchronously with respect to the program 
that closes it 


Note: When the alternate index or component is not stored 
on a mass storage volume, the attribute is ineffective 
until the direct access storage volume on which the 
alternate index or component is stored is converted to a 
Haig storage volume Cusing the CONVERTV command, described 


information’. 


DESTAGEWAIT 
indicates that destaging is to be completed before 
VSAM returns control to the program that issued the 
CLOSE macro. VSAM can thus notify the program whether 
destaging was successful. 


Abbreviation: DSTGW 
NODESTAGEWAIT 
indicates that notification of unsuccessful destaging 
is to be made only by a message to the operator. 
Abbreviation: NDSTGW 
When one of these parameters is specified for the data 
component and the other parameter is specified for the 


Chapter 4. Functional Command Format 69 











DEFINE ALTERNATEINDEX 


index component, the components are destaged separately as 
specified, unless the sequence set of the index component 
is embedded in the data. In that case, the parameter 
specified for the index component applies to both 
components. : 


ERASE | NOERASE 


specifies whether the alternate index data component's 
Fargas are to be erased when the alternate index is 
eleted. 


This attribute applies only to the alternate index's data 
component. 


ERASE 
specifies that the records of the alternate index data 
component are to be overwritten with binary zeros when 
the alternate index is deleted. 


Abbreviation: ERAS 


NOERASE 
specifies that the records of the alternate index data 
component are not to be overwritten with binary zeros. 


Abbreviation: NERAS 


EXCEPTIONEXITCentrvypoint) 


specifies the name of the user-written routine, called the 
exception exit routine, that receives control when an 
exceptional I/0 error condition occurs during the transfer 
of data between your program's address space and the 
alternate index's direct access storage space. (An 

rata 1s any condition that causes a SYNAD exit to be 
aken. 


The component's exception exit routine is processed first, 
then the user's SYNAD exit routine receives control. 


If an exception exit routine is loaded from an unauthorized 
library during access method services processing, an 
abnormal termination will occur. 


Abbreviation: EEXT 


FILE(ddname) 
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names the DD statement that identifies the direct access 
device(s) and volume(s) on which space is to be allocated 
to the alternate index. 


If more than one volume is specified in a volume list, all 
volumes must be of the same device type. When the data 
component and index component are to reside on separate 
devices, you can specify a separate FILE parameter as a 
parameter of DATA and INDEX to point to different DD 
statements. 


When the alternate index is defined in a recoverable 
catalog, and FILE is specified as a parameter of 
ALTERNATEINDEX, the FILE parameter can identify the DD 
statement for all volumes on which space is to be 
allocated. 


When defining into a recoverable catalog, FILE also 
identifies the volume containing the base cluster's index 
component (when the base cluster is key sequenced) or data 
component Cwhen the base cluster is entry sequenced). 


When the alternate index is cataloged in a recoverable 
catalog, the DD statement can be concatenated if the 
volumes are a different device type. Part of the 
concatenated DD statement describes the alternate index's 
or component's volumes Cof one device type); the other part 
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of the DD statement describes the volume that contains the 
catalog recovery area Cof another device type). 


If the FILE parameter is not specified, an attempt is made 
to dynamically allocate the required volumes. The 
volume(s) must be mounted as permanently resident or 
reserved. 


The DD statement you specify must be in the form: 


//ddname DD UNIT=(devtypel »unitcount]), 
// NOL=SER=(volserl,volser2,volser3,..e rece 


Note: When FILE refers to more than one volume of the same 
device type, the DD statement that describes the volumes 
cannot be a concatenated DD statement. 


FREESPACE(CI-percenti CA-percenti1!10 0 ) 


specifies the amount of space that is to be left empty 
after any primary or secondary allocation and any split of 
control intervals (CI-percent) and control areas 
(CA-percent) when the alternate index is built (Csee 
"BLDINDEX®™ on page 49). 


The amount of empty space in the control interval and 
control area 1s available for data records that are updated 
and inserted after the alternate index is initially built. 


The amounts are specified as percentages. 


° CI-percent translates into a number of bytes that is 
equal to, or slightly less than, the percentage value 
of CI-percent. 


6 CA-percent translates into a number of control 
intervals that is equal to, or less than, the 
percentage value of CA-percent. 


The percentages, which must be equal to or less than 
100, can be expressed in decimal (n), hexadecimal 
CX'¥n"), or binary CB'n') form. 


When you specify 100% of free space, one data record is 
placed in the first control interval of each control area 
when the alternate index is built. 


Abbreviation: FSPC . 


IMBED | NOIMBED 


specifies whether the sequence set (the lowest level of the 
index) is to be placed with the alternate index's data : 
component. 


IMBED 
specifies that the sequence-set record for each 
control area is to be written as many times as it will 
fit on the first track adjacent to the control area. 
If the allocation is less than a cylinder, one track 
will be added to the primary and secondary allocation 
quantities. 


Abbreviation: IMBD 


NOIMEBED 
specifies that the sequence-set record for each 
control area is to be written with the other index 
records. 


Abbreviation: NIMBD 


The IMBEDINOIMBED parameter interacts with the 


REPLICATE|NOREPLICATE parameter in determining the physical 
attributes of the index of the alternate index. These 
index attributes can be used in the following combinations: 
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e The sequence-~set records are adjacent to the data 
control areas, and only the sequence-set records are a 
replicated CIMBED and NOREPLICATE). é 





) The sequence~set records are adjacent to the data 
control intervals, and all levels of index records are 
replicated CIMBED and REPLICATE). 


e All index records are together, and all index records 
are replicated CREPLICATE and NOIMBED). 


e All index records are together, and no index records 
are replicated CNOREPLICATE and NOIMBED). 


For some applications, specifying index options can improve 
the application's performance. For information on how the 
index's optional attributes affect performance, see 

ini j Gui ; 


KEYRANGES((lowkey highkey) 
[ Clowkey j ey)...1) 
specifies that portions of the alternate index's data 
component are to be put on different volumes. Each portion 
of the alternate index is called a key range. 


The maximum number of key ranges for an alternate index is 
123. Key ranges must be in ascending order, and are not 
allowed to overlap. However, a gap can exist between two 
key ranges. You cannot insert records within the gap. 


Keys can contain 1 to 64 characters; 1 to 128 hexadecimal 
characters if coded as X'lowkey' X'highkey'. 


e 

specifies the low key of the key range. If lowkey is 

shorter than the actual keys, it will be padded on the pre 
right with binary zeros. 


specifies the high key of the key range. If highkey 
is shorter than the actual Keys, it will be padded on 
the right with binary ones. 


The KEYRANGES parameter interacts with other DEFINE 
ALTERNATEINDEX parameters. You should ensure that the 
KEYRANGES you specify for the alternate index are 
consistent with the alternate index's other attributes. 


e VOLUMES: There should be as many volume serial numbers 
in the volser list as there are key ranges. 


When a volume serial number is duplicated in the volser 
list, more than one key range is allocated space on the 
volume. When more than one key range is to be 
contained on a volume, UNIQUE cannot be coded for the 
alternate index's data component. 


When there are more volumes in the volser list than 
there are key ranges, the excess volumes are used for 
overflow records from any key range without 
consideration for key range boundaries. 


When there are fewer volumes in the volser list than 
there are key ranges, the excess key ranges are 

_ allocated on the last volume specified. UNIQUE cannot 
also be specified. 


@ UNIQUE: When UNIQUE is specified, each key range 
resides in its own VSAM data space on a separate 
volume. Other key ranges for the alternate index 
cannot also reside on the volume. 


° QRDERED: There is a one-to~one correspondence between 
the volumes in the volser list and the key ranges: The 
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first volume on the volume list contains the first key 
range, the second volume contains the second Key range, 
and so on. 


If a volume cannot be allocated in the order specified 
by the volser list, your alternate index definition job 
terminates with an error message. (For example, the 
job would terminate if there were no space on one of 
the volumes specified.) 


e KEYS: The low key and high key values must not exceed 
the key length specified in the KEYS parameter. The 
KEYS parameter must be specified in the same component 
as the KEYRANGE parameter. 


Abbreviation: KRNG 


KEYS(length offsetl64 0 


describes the oe ake key field in the base cluster's 
data record. 


The Key field of an alternate index is called an alternate 

key. The data record's alternate key can overlap or be 
Fl entirely within another Calternate or prime) key 
ield. 


The sum of length plus offset cannot be greater than the 
length of the base cluster's data record. 


When the base cluster's data record is allowed to span 
control intervals, the record's alternate-key field is 
within the record's first segment (that is, in the first 
control interval). 


denath offset 
specifies the length of the alternate key (between 1 
and 255), in bytes, and its displacement from the 
beginning of the base cluster's data record, in bytes. 
You can express length and offset in decimal (n), 
hexadecimal (X'n'"), or binary CBin') form. 


MASTERPW (password) 


specifies a master password for the entry being defined. 
The master password allows all access method services 
operations against the alternate index entry and its data 
and index entries, and allows the user's program to access 
the alternate index's contents without restriction. For 
more details ade passwords can be used, erie 

YU or 


The AUTHORIZATION, CODE, and ATTEMPTS parameters have no 
effect unless the entry has a master password associated 

with it. If MASTERPW is not specified, the highest-~level 
aera specified becomes the password for all higher 
evels. 


Abbreviation: MRPW 


MODELCentrvynamel/password] 
[ catname 


mel/password1]1} 
specifies an existing entry to be used as a model for the 
entry being defined. 


You can use an existing alternate index's entry as a model 
for the attributes of the alternate index being defined. 
For details about how a model is used, see a 


You may use some attributes of the model and override 
others by explicitly specifying them in the definition of 
the cluster or component. If you do not want to add or 
change any attributes, you need specify only the entry type 
Calternate index, data, or index) of the model to be used 
and the name of the entry to be defined. 
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Unless another entry is specified with the MODEL parameter 
as a subparameter of DATA or INDEX, when you use an 
alternate index entry as a model for an alternate index, 
the data and index components of the model entry are used 
as models for data and index components of the entry still 
to be defined. | 


names the entry to be used as a model. 


password 


specifies a password. If the model entry is 
password-protected and it is cataloged ina 
password-protected catalog, you supply the read~ or 
higher-level password of either the model entry or its 
catalog. If you supply both passwords, the catalog's 
password is used. RACF: The read or higher RACF 
authority to the model or catalog is required. 


If you are not specifying new protection attributes 
for the alternate index and you wish to copy the 
model's passwords and protection attributes, you must 
supply the master password of either the model entry 
or its catalog. RACF: The alter RACF authority to the 
model or catalog is required. 


catname 


names the model entry's catalog. You must identify 
the catalog that contains the model entry when: 


° You want to specify the catalog's password instead 
of the model entry's password. 


@ The model entry's catalog is not identified with a 
JOBCAT or STEPCAT DD statement, and is not the 
master catalog. 


If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. For information 
about the order in which a catalog is selected when 
the catalog's name is not specified, see "Order of 
Catalog Selection for DEFINE™ on page 16. 


ORDERED | UNORDERED 


specifies whether volumes are to be used in the order in 
which they are listed in the VOLUMES parameter. 


ORDERED 


specifies that the volumes are to be used in the order 
in which they are listed for the VOLUMES parameter. 


When you want each key range to reside on a separate 
volume, you can use ORDERED so that the first key 
range goes on the first volume, the second Key range 
goes on the second volume, and so on. 


If ORDERED is specified and the volumes cannot be 
allocated in the order specified, the command is 
terminated. (For example, the command would terminate 
if there were no space on one of the volumes 
specified.) 


Abbreviation: ORD 


UNORDERED 


specifies no order for the use of the volumes 
specified in the VOLUMES parameters. 


Abbreviation: UNORD 


OWNER ( ownerid) 


specifies the identification of the alternate index's 
owner. 
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Note to TSO users: 


If the owner is not identified with the OWNER parameter, 
the TSO user's userid becomes the ownerid. 


READPW( password) 


specifies a read password for the entry being defined. The 
read password permits read operations against the entry's 
records. 


When specified as a parameter of DATA or INDEX, the read 
password allows the user's program to open the data 
component or the index component for read-only processing 
of the component's data records (that is, the data portion 
of the sorted record, not the control fields VSAM inserts 
into stored records). For more details on how passwords 
can be used, see ini io ide. 


Abbreviation: RDPW 


RECORDSIZE(average maximum!4086 32600) 


specifies the average and maximum length, in bytes, of an 
alternate index record. 


An alternate index record can span control intervals, so 
RECORDSIZE can be larger than CONTROLINTERVALSIZE. average 
and maximum are any integer values that do not exceed the 
capacity of a control area. It can be expressed in decimal 
(nd), hexadecimal (X'n'), or binary (CB'n") form. You can 
identify the records as fixed length by specifying the same 
value for average and maximum. 


You can use the following formulas to determine the size of 
the alternate index record when the alternate index 
supports: 


e A key sequenced base cluster 
RECSZ = 5 + AIXKL + (Cn x BCKL) 
e An entry sequenced base cluster 
RECSZ = 5 + AIXKL + (n x 4) 
where: 
= RECSZ is the average record size. 


_ AIXKL is the alternate-key length (see the KEYS 
parameter). 


= BCKL is the base cluster's prime-key length Cyou 
can issue the access method services LISTCAT 
command to determine the base cluster's prime-key 
length). 


_ n = 1 when UNIQUEKEY is specified CRECSZ is alsa 
the maximum record size). 


~ n = the number of data records in the base cluster 
that contain the same alternate-key value, when 
NONUNIQUEKEY is specified. 


When you also specify NONUNIQUEKEY, the record size you 
specify should be large enough to allow for as many key 
pointers or RBA pointers as you anticipate. The record 
length values apply only to the alternate index's data 
component. 


Note: REPRO and EXPORT will not support data sets with 
record sizes greater than 32760. 


Abbreviation: RECSZ 
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REPLICATE | NOREPLICATE 


specifies how many times each record in the alternate 
index's index component is to be written on a direct access 
device track. 


For a discussion of the relationship between IMBED|NOIMBED 
sti REPLICATE|NOREPLICATE, see the IMBEDINOIMBED parameter 
above. 


REPLICATE 
specifies that each index record is to be written on a 


DASD track as many times as it will fit. 


When you specify REPLICATE, rotational delay is 
reduced and performance is improved. However, the 
alternate index's index usually takes more direct 
access device space. 


Abbreviation: REPL 


- NOREPLICATE 


specifies that the index record is to be written on a 
DASD track only one time. 


Abbreviation: NREPL 


REUSE | NOREUSE 


specifies whether the alternate index can be used over and 
over aS a new alternate index. 


REUSE 


specifies that the alternate index can be used over 
again as a new alternate index. When a reusable 
alternate index is opened, its high-used RBA can be 
set to zero if you open it with an access control 
block that specifies the RESET attribute. 


When you use BLDINDEX to build a reusable alternate 
index, the high-used RBA is always reset to zero when 


the alternate index is opened for BLDINDEX processing. 


You cannot specify REUSE when you also specify 
KEYRANGES or UNIQUE for the alternate index or its 
components. Reusable alternate indexes may be 


multivolumed and are restricted to 16 physcet extents 


per volume. 


Abbreviation: RUS 


NOREUSE 


specifies that the alternate index cannot be used 
again as a new alternate index. 


Abbreviation: NRUS 


SHAREOPTIONS(crossregionl€ crosssystem]!1 3) 


specifies how an alternate index's data or index component 
can be shared among users. 


For data integrity purposes, you should make sure that 
share options specified for data and index components are 
the same. For a full description of data set sharing, see 


specifies the amount of sharing allowed among regions 
within the same system or within multiple systems 
using global resource serialization (GRS). 
Independent job steps in an operating system or 
multiple systems using GRS can access a VSAM data set 
concurrently. To share a data set, each user must 
specify DISP=SHR in the data set's DD statement. The 
values that can be specified are: 
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specifies that the data set can be shared by any 
number of users for read processing, or the data 
set can be accessed by only one user for read and 
write processing. With this option, VSAM ensures 
complete data integrity for the data set. 


specifies that the data set can be accessed by 
any number of users for read processing and it 
can also be accessed by one user for write 
processing. With this option, VSAM ensures write 
integrity by obtaining exclusive control for a 
control interval when it is to be updated. 


If a user requires read integrity, it is that 
user's responsibility to use the ENQ and DEQ 
macros appropriately to provide read integrity 
for the data the program obtains. (For 
information on using an and DEQ, see System 
Macros and Facilities. 


specifies that the data set can be fully shared 
by any number of users. With this option, each 
user is responsible for maintaining both read and 
write integrity for the data the program 
accesses. 


User programs that ignore the write integrity 
guidelines can cause VSAM program checks, lost or 
inaccessible records, uncorrectable data set 
failures, and other unpredictable results. This 
option places heavy responsibility on each user 
sharing the data set. 


specifies that the data set can be fully shared 
by any number of users, and buffers used for 
direct processing are refreshed for each request. 
This option requires your program to use the ENQ 
and DEQ macros to maintain data integrity while 
sharing the data set. Improper use of the ENQ 
macro can cause problems similar to those 
described under SHAREOPTIONS 3. (CFor information 
on using o and DEQ, see System Macros and 
Faciliti 


Cc ° 


Ss 
specifies the amount of sharing allowed among systems. 
Job steps of two or more operating systems can gain 
access to the same VSAM data set regardless of the 
disposition specified in each step's DD statement for 
the data set. 


To get exclusive control of the data set's volume, a 
task in one system issues the RESERVE macro. The 
level of cross~system sharing allowed by VSAM applies 
only in a multiple operating system environment. The 
values that can be specified are: 


1 

Reserved 
2 

Reserved 
3 


specifies that the data set can be fully shared. 
With this option, each user 1s responsible for 
maintaining both read and write integrity for the 
data that user's program accesses. User programs 
that ignore write integrity guidelines can cause 
VSAM program checks, uncorrectable data set 
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failures, and other unpredictable results. This 
option places heavy responsibility on each user ct 
sharing the data set. + 


specifies that the data set can be fully shared. 
Buffers used for direct processing are refreshed 
for each request. 


This option requires that you use the RESERVE and 
DEQ macros to maintain data integrity while 
sharing the data set. (For information on using 
RESERVE and DEQ, see System Macros and 

Writing is limited to PUT-update 
and PUT- insert processing that does not change 
the high-used RBA if your program opens the data 
set with DISP=SHR. 


Data set integrity cannot be maintained unless 
all jobs accessing the data set in a cross~system 
environment specify DISP=SHR. Improper use of 
the RESERVE macro can cause problems similar to 
those described under SHAREOPTIONS 3. 


To ensure data integrity in a shared environment, VSAM 
provides users of SHAREOPTIONS 4@ Ccross-region and 
cross~system) with the following assistance: 


e Each PUT request results in the appropriate buffer 
being written immediately into the VSAM object's direct 
access device space. VSAM writes out the buffer in the 
user's address space that contains the new or updated 
data record. 


° Each GET request results in all the user's input 
buffers being refreshed. The contents of each data and 
index buffer being used by the user's program are | 
retrieved from the VSAM object's direct access device. ee a 


Abbreviation: SHR 
SPEED | RECOVERY 


specifies whether the data component's control areas are to 
oe ee before alternate index records are loaded 
into them. 


When you specify RECOVERY, your initial load takes longer 
because the control areas are written initially with 
end-of-file indicators and again with your alternate index 
Siegert When you specify SPEED, your initial load is 
quicker. 


SPEED 
; specifies that the data component's space is not to be 
preformatted. Its space might contain data records 
from a previous use of the space, or it might contain 
binary zeros; its contents are unpredictable. 


If the initial load fails, you must load the alternate 
index records again from the beginning because VSAM is 
unable to determine where your last correctly written 
record is. VSAM cannot find a valid end-of-file 
indicator when it searches your alternate index 
records. 


RECOVERY 
specifies that the data component's control areas are 
written with records that indicate end-of-file. When 
an alternate index record is written into a control 





interval, it is always followed by a record that , 
identifies the record that has just been written as ae 
the last record in the alternate index. Rey 
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If the initial load fails, you can resume leading 
alternate index records after the last correctly 
written record, because an end-of-file indicator 
identifies it as the last record. 


Abbreviation: RCVY 


STAGE |BIND|CYLINDERFAULT 


specifies how an alternate index or component that is 
stored ona mass storage volume is to be staged. 


When the alternate index or component is not stored on a 
mass storage volume, the attribute is ineffective until the 
direct access storage volume on which the alternate index 
or component is stored is converted to a mass storage 
volume. (The CONVERTV command used for this conversion is 
aerate ae tor ervi : Re 

r on. 


Unless the sequence set of the index component is embedded 
in the data, when one of these parameters is specified for 
the data component and another parameter is specified for 
the index component, the components are staged separately 
as specified. In that case, the parameter specified for 
the index component applies to both components. 


STAGE 
indicates that the alternate index or component is to 
be staged from mass storage to a direct access storage 
pee bl drive when the alternate index or component is 
opened. 


If the alternate index or component cannot be staged 
at open time because of heavy staging activity of 
other objects, data is staged as the processing 
program needs it. 


BIND 
indicates that the alternate index or component is not 
only to be staged, but also to be bound-——-that is, 
retained on the direct access storage staging drive 
until it is closed. If the alternate index or 
component cannot be staged at open time because of 
heavy staging activity of other objects, data is 
staged as the processing program needs it. 


CYLINDERFAULT 
indicates that the alternate index or component is not 
to be staged when it is opened, but that data from it 
is to be staged as the processing program needs it. 


Abbreviation: CYLF 


TO( date) | FOR(davs) 


specifies the retention period for the alternate index. 

The alternate index is not automatically deleted when the 
expiration date 1s reached. When you do not specify a 
ae period, the alternate index can be deleted at any 
ime. 


TO(date) 
specifies the date, in the form yyddd, where yy is the 
year and ddd is the Julian date (001, for January Il, 
through 365, for December 31), through which the 
alternate index is to be kept before it is allowed to 
be deleted. 


FOR( days) 
specifies the number of days for which the alternate 
index is to be kept before it is allowed to be 
deleted. days can be expressed in decimal (n), 
hexadecimal (X'n'"), or binary CB'n") form. 
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The maximum number that can be specified for days is 


9999. If the number specified is 0 through 1830, the a 
retention period is the number of days specified. If — 
the number specified is between 1831 and 9999, the a 


retention period is through the year 1999. 


UNIQUE | | 
specifies whether the alternate index's components are 
allocated an amount of space from the volume's available 


space CUNIQUE) or from a VSAM data space's available space 
CSUBALLOCATION). 


UNIQUE 
specifies that a VSAM data space is to be built and 
assigned exclusively to each component of the 
alternate index. The data space is created when the 
alternate index is defined. The alternate index's 
volume(s) must be mounted. 


VYSAM builds a DSCB in the volume’s table of contents 
CVTOC) to describe the data space. The name of the 
data space, which is the same as the component's name, 
is put in the DSCB. A subentry is added to the volume 
entry Cin the VSAM catalog) to describe the VSAM data 
space. 


Abbreviation: UNQ 


SUBALLOCATION . 
specifies that space from one of the VSAM data spaces 
on the volume is to be assigned to the alternate 
index's component. 


Abbreviation: SUBAL 


The space allocation attribute interacts with other DEFINE ors 
ALTERNATEINDEX parameters. You should ensure that the 
space allocation attribute you specify for the alternate Se 


index is consistent with other attributes: 


@ REUSE: You cannot specify REUSE when you specify UNIQUE 
for an alternate index or its components. 


e KEYRANGES: When UNIQUE is specified, a data space is 
built and allocated on a separate volume for each key 
range. 


e VOLUMES: When UNIQUE is not specified, VSAM data space 
must exist on the volume that is to contain the 
alternate index's component. 


When UNIQUE is specified, and more than one volume is 
specified, VSAM must already own all the volumes except 
the first. If there is no VSAM space on a volume, you 
must execute a DEFINE SPACE CANDIDATE before your 
DEFINE UNIQUE. | 


UNIQUEKEY | NONUNTQUEKEY 
specifies whether more than one data record Cin the base 
poorer li can contain the same key value for the alternate 
index. 


UNIQUEKEY 
specifies that each alternate index key points to only 
one data record. When the alternate index is built 
(see "BLDINDEX™ on page 49) and more than one data 
record contains the same key value for the alternate 
index, the BLDINDEX processing terminates with an 
error message. 


Abbreviation: UNQK 
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NONUNIQUEKEY 
specifies that a key value for the alternate index can 
point to more ae one data record in the base 
cluster. The alternate index's key record can point 
to a maximum of 32768 records with nonunique Keys. 


When you specify NONUNIQUEKEY, the value you specify 
as the maximum record size should be large enough to 
allow for alternate index records that point to more 
than one data record. 


Abbreviations: NUNQK 
UPDATEPW( password) 


specifies the update password for the entry being defined. 
The update password permits read and write operations 
against the entry's records. 


When specified as a parameter of DATA or INDEX, the update 
password allows the user's program to open the data 
component or index component for read and write processing 
of the component's VSAM records (that is, the data portion 
of the stored record, not the control fields that VSAM 
inserts into stored records). 


If a read password is the only password specified for the 
object (that is, it is the highest-level password), it 
propagates upward and becomes the password for all higher 
levels. If you specify a higher-level password and do not 
sed an update password, the update or read password is 
null. 


Abbreviation: UPDPW 
UPGRADE | NOUPGRADE 


specifies whether the alternate index is to be upgraded 
Sieh | kept up to date) when its base cluster is 
modifie 


UPGRADE 
specifies that the cluster's alternate index is 
upgraded to reflect changed data when the base 
cluster's records are added to, updated, or erased. 


When UPGRADE is specified, the alternate index's name 
is cataloged with the names of other alternate indexes 
for the base cluster. The group of alternate index 
names identifies the upgrade set that includes all the 
base cluster's alternate indexes that are opened when 
the base cluster is opened for write operations. 


The UPGRADE attribute is not effective for the 
alternate index until the alternate index is built 
(see "BLDINDEX™ on page 49). If the alternate index 
is defined when the base cluster is open, the UPGRADE 
attribute takes effect the next time the base cluster 
is opened. 


Abbreviation: UPG 

NOUPGRADE 
specifies that the alternate index is not to be 
upgraded when its base cluster is modified. 


Abbreviation: NUPG 
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WRITECHECK | 


specifies whether an alternate index or component is to be 
checked by a machine action called write check when a 
record is written into it. 


WRITECHECK 
specifies that a record is written and then read, 


without data transfer, to test for the data check 
condition. | 


Abbreviation: WCK 


NOWRITECHECK : 


specifies that the alternate index or component is not 
to be checked by a write check. 


Abbreviation: NWCK 


DATA AND INDEX COMPONENTS OF AN ALTERNATE INDEX 


Attributes can be specified separately for the alternate index's 
data and index components. A list of the DATA and INDEX 
parameters is provided at the beginning of this section. These 
parameters are described in detail as parameters of the 
alternate index as a whole. Restrictions are noted with each 
parameter's description. 
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Define an Alternate Index: Example 1 





DEFINE ALTERNATEINDEX 


In this example, an alternate index is defined. An example for 


DEFINE CLUSTER illustrates the definition of the alternate 
index's base cluster, EXAMPLE.KSDS2. A subsequent example 
illustrates the definition of a path, EXAMPLE.PATH, that allows 
you to process the base cluster's data records using the 
alternate key to locate them. The alternate index, path, and 
base cluster are defined in the same catalog, USERRCAT. 


//DEFAIX1 JOB ee 
//STEPI EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//7SYSIN DD % 

DEFINE ALTERNATEINDEX - 
CNAMECEXAMPLE.AIX) - 
RELATECEXAMPLE.KSDS2) - 
MASTERPWCAIXMRPHWD - 
UPDATEPWCAIXUPPH) —- 
KEYSC3 0) -— 
RECORDSIZEC40 50) - 
VOLUMESCVSERO1) - 
CYLINDERS(C3 1) - 
NONUNIQUEKEY - 

UPGRADE) - 
CATALOGCUSERRCAT/USERUPPW) 
7% 


The DEFINE ALTERNATEINDEX command creates an alternate index 
entry, a data entry, and an index entry to define the alternate 
index EXAMPLE.AIX. The DEFINE ALTERNATEINDEX command also 
obtains space for the alternate index from one of the VSAM data 
spaces on volume VSERO04, and allocates 3 cylinders for the 
alternate index's use. Because the alternate index is being 
defined into a recoverable catalog, the catalog recovery volume 
will be dynamically allocated. The command's parameters are: 


@ NAME, which specifies that the alternate index's name is 
EXAMPLE.AIX. 


e RELATE, which identifies the alternate index's base cluster, 
EXAMPLE.KSDS2. 


e MASTERPW and UPDATEPW, which specifies the alternate index's 
master password, AIXMRPW, and update password, AIXUPPH. 


e KEYS, which specifies the length and location of the 
alternate key field in each of the base cluster's data 
records. The alternate key field is the first three bytes 
of each data record. 


e RECORDSIZE, which specifies that the alternate index's 
records are variable-length, with an average size of 40 
bytes and a maximum size of 50 bytes. 


e VOLUMES, which specifies that the alternate index is to 
reside on volume VSERO1. This example assumes that the 
volume is already cataloged in the user catalog, USERRCAT. 


e CYLINDERS, which specifies that 3 cylinders are allocated 
for the alternate index's space. When the alternate index 
is extended, it is to be extended in increments of l 
cylinder. 


° NONUNIQUEKEY, which specifies that the alternate key value 


might be the same for two or more data records in the base 
cluster. 
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e UPGRADE, which specifies that the alternate index is to be 
opened by VSAM and upgraded each time the base cluster is 
opened for processing. 


e CATALOG, which specifies that the alternate index is to be | 


defined in the user catalog, USERRCAT. The example also 
supplies the master catalog's update password, USERUPPW. 
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( The DEFINE CLUSTER command defines a cluster for a 

Re Key~sequenced, entry-sequenced, or relative record data set. 
When you use this command, you can specify attributes for the 
cluster as a whole and for the components of the cluster. The 
general format of the DEFINE CLUSTER command is: 


DEFINE CLUSTER Cparameters) - 
CDATACparameters)] - 
CINDEXCparameters)] - 
[CATALOGCsubparameters) J 


CLUSTER 

CNAME Centryname) 

{CYLINDERS (primary£€ secondary1])| 
RECORDS(primaryl secondary])| 
TRACKS(primary£ secondary] )} 

VOLUMES(volser[ volser...]) 

[ATTEMPTS (number 12)] 

TAUTHORIZATION(entrypointl string])] 

FBUFFERSPACE(size)]1 

CCODE(code)] 

aS Ph ali alr ca 

[CONTROLPW( password)] 

[DESTAGEWAIT | NODESTAGEWAITI 

[ERASE] NOERASE] 

CEXCEPTIONEXITlCentrvpoint)] 

[FILE(dname)] 

C[FREESPACE(CI-percent 
[ CA-percent]!]0 0)] 

a CLIMBED | NOZMBED ] 
( [INDEXED ] NONINDEXED | NUMBERED] 
ni oukey, hiahke } 


[KEYS( length 

[MASTERPH (password) } 

rMODEL (entrynanel /password] 
[ cat nanel/password]])1 

[ORDERED | UNORDERED] 

[COWNER( ownerid)] 

C[READPW( password)! 

[TRECORDSIZEl(average maximum)1] 

[REPLICATE | NOREPLICATE] 

[REUSE | NOREUSE] 

PSHAREOP T TONS (oresered.on 

crosssystem]|]1 331] 

ESPANNED | NONSPANNED] 

[SPEED] RECOVERY] 

[STAGE [BIND|CYLINDERFAULT] 

[TO(date) |FOR( days)! 

[UNIQUE | SUBALLOCATION] 

[UPDATEPW(password)] 

[WRITECHECK | NOWRITECHECK] ) 





CContinued on next page.) 
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DEFINE can be abbreviated: DEF ev 


ATA 
CLATTEMPTS (number )1 ( 





[AUTHORIZATION(Centrypointl stringl)I | aed 
[BUFFERSPACE (size)] | . ; ; 
[CODE(code)] 
[CONTROLINTERVALSIZE(size)] 
[CONTROLPW( password)] 
[CYLINDERS(primary£€ secondary!) 
RECORDS(primaryl€ secondary] )| 
TRACKS(primaryvi secondary] )] 
[DESTAGEWATT | NODESTAGEWATT 1 
[ ERASE | NOERASE] 
CEXCEPTIONEXIT(entrypoint)] 
[FILE(dname)] 
[FREESPACE(CI-percentl( CA-percent])] 
C[KEYRANGES( ( lowkey } ) 
[ ( highkey),,.1)1 


lLowkey 
[KEYS(length offset)] 
[MASTERPW( password)] 
[MODEL(Centrynamnel/password] 
sa catnamel/password] }] 


ECentryname)] 
recite 1a aod piace aa 
[OWNER( ownerid)] 
CREADPW( password) ] 
[RECORDSIZElaverage maximum) 
[REUSE ] NOREUSE] 
[SHAREOPTIONS(crossregionl crosssystem])] 
{ SPANNED | NONSPANNED ] 
[SPEED[ RECOVERY] 
[STAGE|BIND| CYLINDERFAULT] 
HAE bat bedibet en OE 
[UPDATEPW( password) ] 
CVOLUMES(volser[ volser...1)] 
[WRITECHECK | NOWRITECHECK] } J ye “Hy 


[INDEX 


(LATTEMPTS (number J1 
[AUTHORIZATIONCentrypointl€ string])] 
[CODE(code)] 
pee HURT teeter el 
[CONTROLPW(password)] 
[CYLINDERS (primaryvl 
RECORDS (primaryl 
TRACKS(primary[ secondary]) 
[DESTAGEWAIT |NODESTAGEWAIT]I 
CEXCEPTIONEXITlCentrvpoint)] 
CFILE(dname)] 
[IMBED |NOIMBED] 
CHAS TERPW (password) 1 


entryname)] 
CORDERED]UNORDERED] 
[OWNER( ownerid)] 

CREADPW( password)1] 

CLREPLICATE |NOREPLICATE] 

[REUSE |NOREUSE] : 
[SHAREOPTIONS(crossregionl crosssystem])] 
[STAGE |BIND|CYLINDERFAULT] 

ey Ene learn le 

[CUPDATEPW( password) ] 

[VOLUMES(volser[ volser...])] 
[WRITECHECKINOWRITECHECKI 11 


[CATALOG( catnamel/password])] 
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DEFINE CLUSTER PARAMETERS 


Required Parameters 


CLUSTER 
specifies that a cluster is to be defined. 


The CLUSTER keyword is followed by the parameters specified 
for the cluster as a whole. These parameters are enclosed 
in parentheses and, optionally, are followed by parameters 
specified separately for the DATA and INDEX components. 


Abbreviation: CL 
NAME Centryname) 


specifies the cluster's entryname or the name of each of 
its components. The entryname specified for the cluster as 
a whole is not propagated to the cluster's components. 


You can define a separate entryname for the cluster, its 
data component, and its index component. If no name is 
specified for the data and index component, a name is 
generated. When the cluster, data component, and index 
component are individually named, each can be addressed. 


CYLINDERS(primary£ secondary])I| 
RECORDS(primaryl€ secondaryl)|{ 


TRACKS(primaryl secondary]) 
specifies the amount of space to be allocated to the 


cluster from the volume's available space, when UNIQUE is 
specified, or from the available space of one of the 
volume's VSAM data spaces. | 


If you do not specify the MODEL parameters, you must 
specify one, and only cone, of the following parameters: 
CYLINDERS, RECORDS, or TRACKS. 


When you specify UNIQUE, space is always allocated in 
cylinders. If the amount of space you specify for the data 
component of the cluster is not an even multiple of 
cylinder size, VSAM rounds the allocation upward to a 
multiple of a cylinder. 


If you specify RECORDS, the amount of space allocated is 
the minimum number of tracks that are required to contain 
the specified number of records. 


Regardless of the allocation type, the control area (CA) 
size for the data set is calculated based on the smaller of 
the two allocation quantities (primary or secondary) 
specified in the define command. A CA 1s never greater than 
a single cylinder, but may be less (that is, some number of 
tracks) depending upon the allocation amount and type used. 
When tracks or records are specified, the space allocation 
unit (the CA size) may be adjusted to one cylinder. This 
occurs if the calculated CA size contains more tracks than 
exist ina single cylinder of the device being used. 


DEFINE RECORDS will allocate sufficient space to contain 
the specified number of records, but variable factors 
unknown at define time (such as Key compression or method 
of loading records) may result in inefficient use of the 
space allocated. This may prevent every data CA from being 
completely used, and you may be unable to load the 
specified number of records without requiring secondary 
allocation. 


When UNIQUE or REUSE is specified, each volume can contain 
a maximum of 16 extents. 


When the data component is not divided into key ranges and 
more than one volume is specified, the primary amount of 
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space is allocated only on the first volume when the 
component is defined. The secondary amount must be coded 
to extend the component to additional volumes. When the 
component increases in size so as to extend to additional 
volumes, the first allocation on each overflow volume is 
the primary amount. 


When KEYRANGES is specified and the data component is to be 
contained on more than one volume, the primary amount of 
Space is immediately allocated on each volume required for 
the key ranges. If more than one key range is allocated on 
a single volume, the primary amount is allocated for each 
key range. 


Secondary amounts can be allocated on all volumes available 
to contain parts of the cluster regardless of the key 


- ranges. 


You can specify the amount of space as a parameter of 


CLUSTER, as a parameter of DATA, or as a parameter of both 
DATA and INDEX. When a key-sequenced cluster is being 
defined and the space is specified as a parameter of: 


e CLUSTER, the amount specified is divided between the 
data and index components. The division algorithm is a 
function of control interval size, record size, device 
type, and other data set attributes. 


If the division results in an allocation for the data 
component that is not an integral multiple of the 
required control area size, the data component's 
allocation is rounded up to the next higher control 
area multiple. This rounding may result ina larger 
total allocation for your cluster than you specified. 


e DATA, the entire amount specified is allocated to the 
data component. An additional amount of Space, 
depending on control interval size, record size, device 
type, and other data set attributes, is allocated to 
the index component. 


To determine the exact amount of space allocated to each 
component, list the cluster's catalog entry, using the 
LISTCAT command. 


When you specify UNIQUE, and the cluster's data space is 
the first data space on a volume that belongs to a 
recoverable catalog, the equivalent in tracks of one 
additional cylinder is allocated for the recovery area data 
space. 


The primary and each secondary allocation must be able to 
be satisfied in 5 extents; otherwise, your DEFINE or data 
set extension will fail. 


specifies the initial amount of space that is to be 
allocated to the cluster. 


specifies the amount of space that is to be allocated 
each time the cluster extends, as a secondary extent. 
When secondary is specified and the cluster is 
suballocated, space for the cluster's data and index 
coe one Ts can be expanded to include a maximum of 123 
extents. 


If the data space that contains all or part of the 
cluster cannot be extended because the cluster's 
secondary allocation amount is greater than the data 
space'’s secondary allocation amount, VSAM builds a new 
data space. The new data space's primary and 
secondary allocation amounts are equal to the 
cluster's secondary allocation amount. 
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primary and secondary can be expressed in decimal (n), 
hexadecimal (X'n'), or binary (B'n") form. 


Abbreviations: CYL, REC, and TRK 


VOLUMES(volser[f vyolser...]) 
specifies the volume(s) on which a cluster's components are 
to have space. 


If you do not specify the MODEL parameter, VOLUMES must be 
specified either as a parameter of CLUSTER, or as a 
parameter of both DATA and INDEX. 


If the data and index components are to reside on different 
device types, you must specify VOLUMES as a parameter of 
both DATA and INDEX. 


If more than one volume is listed with a single VOLUMES 
parameter, the volumes must be of the same device type. 


The volume serial number may be repeated in the list only 
if the KEYRANGE parameter is specified. You may want to do 
this in order to have more than one key range on the same 
volume. Even in this case, repetition is only valid if all 
duplicate occurrences are used for the primary allocation 
of some key range. 


In a system with the Mass Storage System, a cluster or 
component can be defined on a mass storage volume. 


The VOLUMES parameter interacts with other DEFINE CLUSTER 
parameters. You should ensure that the volume(Cs) you 
specify for the cluster is consistent with the cluster's 
other attributes: 


e SUBALLOCATION: If UNIQUE is not specified, the volume 
must already contain VSAM data space. 


% KEYRANGES: If KEYRANGES and UNIQUE are specified, a 
VSAM data space is built and allocated on a separate 
volume for each key range. 


e ORDERED: If ORDERED is specified, the volumes are used 
in the order listed. If ORDERED and KEYRANGES are 
specified, there is a one-to-one correspondence between 
the key ranges in the Key range list and the volumes in 
the volser list. 


e CYLINDERS, RECORDS, TRACKS: The volume(s) must contain 
enough unallocated space to satisfy the component's 
primary space requirement. 


6 FILE: The volume information supplied with the DD 
statement (s) pointed to by FILE must be consistent with 
the information specified for the cluster and its. 
components. 


e CATALOG: The data space on the volume must be defined 
before the cluster, and the catalog specified must own 
the volume. 


Abbreviation: VOL 
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Optional Parameters 
ATTEMPTS (number 12) 


specifies the maximum number of times the operator can try 
to enter a correct password in response to a prompting 
message. This parameter only has effect when the entry's 
master password is not null. A prompting message is issued 
only when the user has not already supplied the appropriate 
password. 


number ; — 
can be any number, 0 through 7. If 0 is specified, 
the operator is not prompted and is not allowed to 
enter a password from the console. number can be 
expressed in decimal (n), hexadecimal (X'n'), or 
binary (B'n') form. 


Note to TSO Users: At a TSO terminal, the logon 
password is checked first, before the user is prompted 
to supply a password for the cluster. Checking the 
logon password counts as one attempt to obtain a 
password. If ATTEMPTS is not specified, the user has 
one attempt to supply the cluster's password, because 
the default is 2 


Abbreviation: ATT 
AUTHORIZATION(entrypointl( string!) 


specifies that a user-security~verification routine CUSVR) 
is available for additional security verification. When a 
protected cluster is accessed and the user supplies a 
correct password other than the cluster's master password, 
the USVR receives control. For details on the USVR, see 


If a USVR is loaded from an unauthorized library during 
access method services processing, an abnormal termination 
will occur. 


This parameter only has effect when the entry's master 
password is not null. 


specifies the name of the user's-security-verification 
routine. 


specifies information to be passed on to the USVR when 
it receives control to verify authorization. 


Abbreviation: AUTH 


BUFFERSPACE (size) | 
specifies the minimum space to be provided for buffers. 
The buffer space size you specify helps VSAM determine the 
data component's and index component's control interval 
size. If BUFFERSPACE is not coded, VSAM attempts to get 
enough space to contain two data component control 
intervals and, if the data is key sequenced, one index 
component control interval. 


size 
is the amount of space to be provided for buffers. 
Size can be expressed in decimal (n), hexadecimal 
as Ae binary (CB'n') form, but must not exceed 
7 , 
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The size specified cannot be less than enough space to 
contain two data component control intervals and, if 
the data is key sequenced, one index control interval. 
If the specified size is less than VSAM requires for 
the buffers needed to run your job, VSAM terminates 
your DEFINE and provides an appropriate error message. 


Abbreviations: BUFSP or BUFSPC 
CATALOG( catnamel /password] ) 


identifies the catalog in which the cluster is to be 
defined. For information about the order in which catalogs 
are cerns Oat see "Order of Catalog Selection for DEFINE" 
on page 


specifies the name of the catalog in which the entry 
is to be defined. 


Password 
specifies the catalog's password. If the catalog is 
password protected, you must supply the update~- or 
higher-level password. If no password is specified, 
VSAM will prompt the operator for the correct 
password. RACF: The update or higher RACF authority 
to the catalog is required. 


If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. 


Abbreviation: CAT 
CODE( code) 


specifies a code name for the entry being defined. If an 
attempt is made to access a password protected entry 
without a password, the code name is used in a prompting 
nessage. The code enables the operator to be prompted for 
the password without disclosing the name of the entry. 


If CODE is not specified and an attempt is made to access a 
cluster or component that is password protected without 
supplying a password, the operator will be prompted with 
the name of the entry. 


This parameter only has effect when the cluster's or 
component's master password is not null 


CONTROLINTERVALSIZE(size) 
specifies the size of the control interval for the cluster 
or component. 


If CONTROLINTERVALSIZE is specified on the cluster level, 
it propagates to the component level at which no 
CONTROLINTERVALSIZE has been specified. 


The size of the control interval depends on the maximum 
size of the data records and the amount of buffer space you 
provide. If the size you specify is not an integer 
multiple of 512 or 2048, VSAM selects the next higher 
multiple for your cluster's control interval size. 


If CONTROLINTERVALSIZE is not coded, VSAM determines the 
size of control intervals. If you have not specified 
BUFFERSPACE and the size of your records permits, VSAM uses 
the optimum size for the data component and 512 for the 
index component. 
size 

for a cluster's data component. 

If SPANNED is not specified, the size of a data 


control interval must be at least 7 bytes larger than 
the maximum record length 
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If the control interval specified is less than maximum 
record length plus a 7-~byte overhead, then VSAM will 
increase the data control interval size to contain the 
maximum record length plus the needed overhead. 


If SPANNED is specified, the control interval size can 
be less than the maximum record length. The sizes you 
can specify Cbetween 512 and 32768 bytes) are an 
integer multiple of 512 or 2048: 

CISZ = (n x 512) or (n x 2048) 


where n is a positive integer from 1 to 16. 


for a key-~sequenced cluster'’s index component. 
You can specify the foliowing values: 
CISZ = [512 | 1024 | 2048 | 4096] 


When you specify a size that is not a multiple of 512 or 
2048, VSAM chooses the next higher multiple. 


For a discussion of the relationship between control 
interval size and physical block size, refer to "Optimizing 
VSAM Performance™ in VSAM Administration Guide. The 
discussion also includes restrictions that apply to control 
interval size and physical block size. 


Abbreviations: CISZ or CNVSZ 


CONTROLPW( password) 


specifies a control password for the entry being defined. 


When specified as a parameter of DATA or INDEX, the control 
password allows the user's program to open the data 
component or index component for read and write processing 
of the component's control intervals (that is, the entire 
control interval, including the data portion of stored 
records and the control fields VSAM inserts into stored 
records and control intervals). 


If a read or update password is the only password specified 
for the object, it (the highest-level password) propagates 
ee and becomes the password for all higher unspecified 
levels. 


Abbreviation: CTLPW 


DESTAGEWATT | NODESTAGEWAIT 


specifies whether a cluster or its component that is stored 
on a mass storage volume is to be destaged synchronously or 


- asynchronously with respect to the program that closes it. 


Note: When the cluster or component is not stored on a 
mass storage volume, the attribute is ineffective until the 
direct access storage volume the cluster or component is 
stored on is converted to a mass storage volume by way of 
the CONVERTV mae CCONVERTV is described in YA 5 
Orage 2s2yvs ten id eryices: Reference Info lation. 


DESTAGEWAIT 
indicates that destaging is to be completed before 
VSAM returns control to the program that issued the 
CLOSE macro. VSAM can thus notify the program whether 
destaging was successful. 


Abbreviation: DSTGW 


92 MVS/XA VSAM Catalog: Access Method Services Reference 





a 




















DEFINE CLUSTER 


NODESTAGEWAIT 
indicates that notification of unsuccessful destaging 
is to be made only by a message to the operator. 


Abbreviation: NDSTGW 


When one of these parameters is specified for the data 
component and the other parameter is specified for the 
index component, the components are destaged separately as 
specified, unless the sequence set of the index component 
is embedded in the data. In that case, the parameter 
specified for the index component applies to both 
components. 


ERASE | NOERASE 
specifies whether the cluster's data component is to be 
erased when its entry in the catalog is deleted. 


ERASE 
specifies that the data component is to be overwritten 
with binary zeros when its catalog entry is deleted. 


Abbreviation: ERAS 


NOERASE 
specifies that the data component is not to be 
overwritten with binary zeros. 


Abbreviation: NERAS 
EXCEPTIONEXIT(lCentrypoint) 


specifies the name of a user-written routine, called the 
exception exit routine, that receives control when an 
exceptional I/0 error condition occurs during the transfer 
of data between your program's address space and the 
cluster's direct access storage space. 


An exception is any I/0 error condition that causes a SYNAD 
exit to be taken. The component's exception-exit routine 
is processed first, then the user's SYNAD-~exit routine 
receives control. 


If an exception exit routine is loaded from an unauthorized 
library during access method services processing, an 
abnormal termination will occur. See 


Abbreviation: EEXT 
FILE( dname) 


names the DD statement that identifies the direct access 
device(s) and volumeCs) on which space is to be allocated 
to the cluster. If more than one volume is specified, all 
volumes must be the same device type. 


If data and index components are to reside on separate 
devices, you can specify a separate FILE parameter as a 
parameter of DATA and INDEX to point to different DD 
statements. 


When the cluster is defined in a recoverable catalog, and 
FILE is specified as a parameter of CLUSTER, the FILE 
parameter can identify the DD statement for all volumes on 
which space is to be allocated. The DD statement can be 
concatenated if the volumes are of different device types: 
Part of the concatenated DD statement describes the 
cluster's or component's volume(s) of one device type; the 
other part of the DD statement describes the volume that 
dpa aide the catalog recovery area Cof another device 
ype). 


If the FILE parameter is not specified, an attempt is made 
to dynamically allocate the required volumes. The 
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volume(s) must be mounted as Pernanens hy resident or 
reserved. | | | 


The DD statement you specify must be in the form: 


//ddname DD UNIT=(devtypel»unitcount]), 
Sf VOL=SER=(volserl,volser2,volser,..+Jyee. 


Note: When FILE refers to more than one volume of the same 
device type, the DD statement that describes the volumes 
cannot be a concatenated DD statement. 


FREESPACE(CI-percentl CA-percent]19 9) 
specifies the amount of space that is to be left free when 
the cluster is loaded and after any split of control 
intervals (CI-percent) and control areas (CA-percent). 


The amount of empty space in the control interval and 
control area is available for data records that are updated 
and inserted after the cluster is initially loaded. This 
parameter applies only to key~sequenced clusters. 


The amounts are specified as percentages. 


@ CI-percent translates into a number of bytes that is 
equal to, or slightly less than, the percentage value 
of CI-percent. 


e CA-percent translates into a number of control 
intervals that is equal to, or less than, the 
percentage value of CA-percent. 


CI-percent and CA-percent, which must be equal to or less 
than 100, can be expressed in decimal (n), hexadecimal 
CX'n*¥), or binary CB'n") form. 


When you specify FREESPACEC100 100), one data record is 
placed in each control interval used for data and one 
control interval in each control area is used for data 
(that is, one data record is stored in each control area 
when the data set is loaded). When no FREESPACE value is 
coded, the default specifies that no free space be reserved 
when the data set is loaded. 


When you define the cluster using the RECORDS parameter, 
' the amount of free space specified is not taken into 
consideration in the calculations to determine primary 
allocation. 


Abbreviation: FSPC 
IMBED|NOIJMBED 


specifies whether the sequence set (the lowest level of the 
index) is to be placed with the data component. 


IMBED | 
specifies that the sequence-set record for each 
control area is written as many times as it will fit 
on the first track adjacent to the control area. If 
the allocation is less than a cylinder, one track will 
be added to the primary and secondary allocation 
quantities. 


Abbreviation: IMBD 

NOIMBED 
specifies that the sequence-set record for each 
control area is written with the other index records. 
Abbreviation: NIMBD 


The IMBED|NOIMBED parameter interacts with the 
REPLICATE|INOREPLICATE parameter in determining the physical 
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attributes of the index of the cluster. These index 
attributes can be used in the following combinations: 


® The sequence set records are adjacent to the data 
control areas, and only the sequence set records are 
replicated CIMBED and NOREPLICATE). 


e The sequence set records are adjacent to the data 
control intervals, and all levels of index records are 
replicated CIMBED and REPLICATE). 


® All index records are together, and all index records 
are replicated CREPLICATE and NOIMBED). 


e All index records are together, and no index records 
are replicated CNOREPLICATE and NOIMBED). 


For some applications, specifying index options can improve 
the application's performance. For information on how the 
index's optional attributes affect performance, see 


INDEXED | NONINDEXED | NUMBERED 


specifies the type of data organization that the cluster is 
to have. 


When a cluster is defined, you specify whether the data is 
to be indexed (key~sequenced), nonindexed Centry 
sequenced), or numbered (relative record). 


Certain parameters apply only to Key~sequenced clusters, as 
noted in the description of each of these parameters. 


If you do not specify the data organization and you also do 
not specify the MODEL parameter, your cluster will default 
to key-~sequenced (indexed). 


If you wish to define either an entry-sequenced or relative 
record cluster, you must specify the NONINDEXED or NUMBERED 
parameter unless you specify the MODEL parameter. 


The data organization you select must be consistent with 
other parameters you specify. 


INDEXED 
specifies that the cluster being defined is for 
key-sequenced data. If INDEXED is specified, an index 
component is automatically defined and cataloged. The 
data records can be accessed by key or by relative 
byte address CRBA). 


Abbreviation: IXD 


NONINDEXED 
specifies that the cluster being defined is for 
entry-~sequenced data. The data records can be 
ae sequentially or by relative byte address 


Abbreviation: NIXD 


NUMBERED 
specifies that the cluster’s data organization is for 
relative record data. A relative record cluster is 
Similar to an entry-~sequenced cluster, and has 
fixed-length records that are stored in slots. Empty 
slots hold space for records to be added later. The 
data records are accessed by relative record number 
(slot number). 


Abbreviation: NUMD 
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KEYRANGES((lowkey highkey) 
C(lowkey highkey)...1) 
specifies that portions of Key-~sequenced data are to be 
placed on different volumes. Each portion of the data is 
called a key range. This parameter applies only to 
key-~sequenced clusters. 





The maximum number of Key ranges is 123. Keyranges must be 
in ascending order, and are not allowed to overlap. A gap 
can exist between two key ranges, but you cannot insert 
records whose keys are within the gap. The space to be 
allocated for each Key range must be contiguous. 


‘Keys can contain 1 to 64 characters; 1 to 128 hexadecimal 
characters if coded as X'lowkey' X*highkey'. 


specifies the low Key of the key range. If lowkey is 
shorter than the actual keys, it will be padded on the 
right with binary zeros. 


e 

specifies the high key of the key range. If highkey 
is shorter than the actual keys, it will be padded on 
the right with binary ones. 


The KEYRANGES parameter interacts with other DEFINE CLUSTER 
parameters. You should ensure that your specification of 
KEYRANGES is consistent with the cluster's other 
attributes. 


e VOLUMES: There should be as many volume serial numbers 
in the volser list as there are key ranges. When a 
volume serial number is duplicated in the volser list, 
ae than one Key range is allocated space on the 
volume. 


When more than one Key range is to be contained ona er: 
volume, UNIQUE cannot be coded for the cluster's data 
component. 


When there are more volumes in the volser list than 
there are key ranges, the excess volumes are used for 
overflow records from any key range without 
consideration for key range boundaries. 


When there are fewer volumes in the volser list than 
there are key ranges, the excess key ranges are 
allocated on the last volume specified, and UNIQUE 
cannot also be specified. 


e UNIQUE: When UNIQUE is specified, each Key range 
resides on its own volume in its own VSAM data space. 
Other key ranges for the cluster cannot also reside on 
the volume. 


e ORDERED: There is a one-to-one correspondence between 
the volumes in the volser list and the key ranges: The 
first volume on the volser list contains the first key 
eee the second volume contains the second key range, 
and so on. 


If a volume cannot be allocated in the order specified 
by the volser list, your cluster definition Job 
terminates with an error message. (For example, the job 
would terminate if there were no space on one of the 
specified volumes.) 


e KEYS: The low key and high key values must not exceed 
the key length specified in the KEY parameter. The KEY | 
parameter must be specified in the same component as ‘ne 
the KEYRANGE parameter. ‘eo 


Abbreviation: KRNG 
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KEYS(length offset!64 9) 


specifies information about the prime key field of a 
key-sequenced data set's data records. This parameter 
applies only to key~sequenced clusters. The default 
specifies a key field of 64 bytes in length, beginning at 
the first byte (byte 0) of each data record. 


The key field of the cluster's index is called the prime 
key to distinguish it from other keys, called alternate 
keys. For more details on how to specify alternate indexes 
for a cluster, see "DEFINE ALTERNATEINDEX®™ on page 6 


When the data record is allowed to span control intervals, 
the record's Key field must be within the part of the 
record that is in the first control interval. 


lenath offset ; ; 

specifies the length of the key and its displacement 
Cin bytes) from the beginning of the record. The sum 
of length plus offset cannot exceed the length of the 
shortest record. 


The length of the key can be 1] to 255 bytes. Length 
and offset can be expressed in decimal (n), 
hexadecimal (X'n'"), or binary CB'n') form. 


MASTERPW (password) 
specifies a master password for the entry being defined. 
The master password allows all access method services 
operations against the cluster entry and its data and index 
entries, and allows the user's program to access the 
cluster's contents without restriction. For more details 
on how passwords can be used, see "Security Protection" in 

a ' 


The AUTHORIZATION, CODE, and ATTEMPTS parameters have no 
effect unless the entry has a master. password associated 

with it. If MASTERPW is not specified, the highest-level 
ieee specified becomes the password for all higher 
evels. 


Abbreviation: MRPW 


MODEL Centrynamel cpasswords 
[ catnamel/password]] 
specifies an eas entry to be used as a model for the 
entry being defined. 


You can use an existing cluster'’s entry as a model for the 
attributes of the cluster being defined. For details about 
how a model is used, see fe) rati / ‘ 


You may use some attributes of the model and override 
others by explicitly specifying them in the definition of 
the cluster or component. If you do not want to add or 
change any attributes, specify only the entry type 
(cluster, data, or index) of the model to be used and the 
name of the entry to be defined. 


Unless another entry is specified with the MODEL parameter 

as a subparameter of DATA or INDEX, when you use a cluster 
entry as a model for the cluster, the data and index 

entries of the model cluster are used as models for the 
a ha index components of the cluster still to be 
efined. 


specifies the name of the cluster or component entry 
to be used as a model. 


Specifies a password. If the model entry is 
password-protected and it is cataloged ina 
password-protected catalog, you must supply the read- 
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or higher-level password of either the model entry or 
its catalog. If both passwords are supplied, the os 
catalog's password is used. RACF: The read or higher ( 
RACF authority to the model or catalog is required. % 





If you are not specifying new protection attributes 
for the cluster (that is, the model's passwords and 
protection attributes are being copied), you must 
supply the master password of either the model entry 
or its catalog. RACF: The alter RACF authority to the 
model or catalog is required. 


catname 


names the model entry's catalog. You identify the 
catalog that contains the model entry for either of 
these cases: 





e You specify the catalog's password instead of the 
| model entry's password. 


e The model entry's catalog is not identified with a 
JOBCAT or STEPCAT DD statement, and is not the 
master catalog. 


If the catalog's volume 18S physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. For information 
about the order in which a catalog is selected when 
the catalog's name is not specified, see "Order of 
Catalog Selection for DEFINE™ on page 16 


ORDERED | UNORDERED 


specifies whether volumes are to be used in the order in 
which they are listed in the VOLUMES parameter. 


ORDERED 
specifies that the volumes are to be used in the order 
in which they are listed for the VOLUMES parameter. 


When you want each Key range to reside on a separate 
volume, you can use ORDERED so that the first key 
range goes on the first volume, the second Key range 
goes on the second volume, and so on. 


If ORDERED is specified and the volumes cannot be 
allocated in the order specified, the command 1s 
terminated. (For example, the command would terminate 
if there were no space on one of the volumes 
specified.) 


Abbreviation: ORD 


UNORDERED 
specifies no order for the use of the volumes 
specified in the VOLUMES parameters. 


Abbreviation: UNORD 
OWNER ownerid) 


specifies the identification of the cluster's owner. 


Note to TSO Users: If the owner is not identified with the 
OWNER parameter, the TSO user's userid becomes the ownerid. 


READPW( password) 


specifies a read password for the entry being defined. The 
read password permits read operations against the entry's 





records. 
Abbreviation: RDPW 
RECORDSIZE(average maximuml default) 


specifies the average and maximum lengths, in bytes, of the 
records in the data component. 
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RECORDSIZE can be specified as a parameter of either 
CLUSTER or DATA. 


average and maximum are integer values and can be expressed 
in decimal (nd, hexadecimal (X'n*), or binary CB'n'") form. 
The minimum record size that you can specify is one byte. 


For nonspanned records, the maximum record size + 7 cannot 
exceed the data component's control interval size (that is, 
the maximum nonspanned record size, 32 761 + 7 equals the 
maximum data component control interval size, 32 768). 


For spanned records, the maximum record size cannot exceed 
the number of control intervals per control area times the 
quantity control interval size less 10, as calculated by 
VSAM. When you specify a record size that is larger than 
Ae ae interval, you must also specify spanned records 


You can identify the records as fixed length by specifying 
the same value for average and maximum. If NUMBERED is 
also specified, the records must be fixed length (that is, 
average equals maximum). 
When your records are fixed length, you can use the 
following formula to find a control interval size that 
contains a whole number (n) of records: 

CISZ = (n x RECSZ) + 10 


or 


RECSZ 
When SPANNED or NUMBERED is specified: 
CISZ =Cn x CRECSZ + 3)) + G 


or 


CRECSZ + 3) 
where: 


6 n is the number of fixed-length records in a control 
interval, and is a positive integer. 


° CISZ is the control interval size (see 
CONTROLINTERVALSIZE parameter). 


e RECSZ is the average record size. 
when SPANNED is specified, the default is 
RECORDSIZEC4086 32600). Otherwise, the default is 
RECORDSIZECG089 4089). 

Caution: When you specify RECORDS, you should ensure that: 


RECCsec) x RECSZCavg) > RECSZ(Cmax) 


where: : 

e REC(Csec) is the secondary space allocation quantity, in 
records. 

e RECSZCavg) is the average record size (default = 4086 
or 4089 bytes). 

6 RECSZ( max) is the maximum record size (default = 4089 


or 32600 bytes). 
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When the SPANNED record size default prevails (32600 
bytes), the secondary allocation avanke sy should be at 
least 8 records. 


Note: REPRO and EXPORT will not support data sets with 
record sizes greater than 32760. 


Abbreviation: RECSZ 
REPLICATE | NOREPLICATE 


specifies how many times each index record is to be written 
on a track. 


REPLICATE 
specifies that each index record is to be written ona 
track as many times as it will fit. With REPLICATE, 
rotational delay is reduced and performance is 
improved. However, the cluster's index usually 
requires more direct access device space. 





This parameter applies only to key~sequenced clusters. 
Abbreviation: REPL 


NOREPLICATE 
specifies that the index records are to be written on 
a track only one time. 


Abbreviation: NREPL 


For a discussion of the relationship between IMBED|NOIMBED 
and REPLICATE|NOREPLICATE, see the description of the 
IMBED|NOIMBED parameter. 


REUSE | NOREUSE 
specifies whether the cluster can be opened again and again 
as a reusable cluster. 


REUSE 
specifies that the cluster can be opened again and 
again as a reusable cluster. When a reusable cluster 
1s opened, its high-used RBA 1s set to zero if you 
open it with an access control block that specifies 
the RESET attribute. 


REUSE allows you to create an entry~sequenced, 
Key-~sequenced, or relative record work file. 


When you create a reusable cluster, you cannot build 
an alternate index to support it. Also, you cannot 
create a reusable cluster with key ranges (see the 
KEYRANGE parameter) or with its own data space (see 
the UNIQUE parameter). Reusable data sets may be 
multivolume and are restricted to 16 physical extents 
per volume. 


Abbreviation: RUS 
NOREUSE 


specifies that the cluster cannot be opened again as a - 


new cluster. 
Abbreviation: NRUS 


SHAREOPTIONS(crossregion£ crosssysteml|1 3) 
specifies how a component or cluster can be shared among 
users. For a description of data set sharing, see 
Administration Guide. To ensure integrity, you should be 
sure that share options specified at the DATA and INDEX 
levels are the same. 


r 


specifies the amount of sharing allowed among regions 
within the same system or within multiple systems 
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using global resource serialization (CGRS). 
Independent job steps in an operating system or 
multiple systems using GRS can access a VSAM data set 
concurrently. The values that can be specified are: 


1 





specifies that the data set can be shared by any 

number of users for read processing, or the data 

set can be accessed by only one user for read and 
write processing. With this option, VSAM ensures 
complete data integrity for the data set. 


specifies that the data set can be accessed by 
any number of users for read processing and it 
can also be accessed by one user for write 
processing. 


With this option, VSAM ensures write integrity by 
obtaining exclusive control for a control 
interval when it is to be updated. If a user 
desires read integrity, it is that user's 
responsibility to use the ENQ and DEQ macros 
appropriately to provide read integrity for the 
data the program obtains. (For information on 
using ENQ ate DEQ, see e fe] 


specifies that the data set can be fully shared 
by any number of users. With this option, each 
user is responsible for maintaining both read and 
write integrity for the data the program 
accesses. 


guidelines can cause VSAM program checks, lost or 
inaccessible records, uncorrectable data set 
failures, and other unpredictable results. This 
option places heavy responsibility on each user 
sharing the data set. 


( User programs that ignore the write integrity 


specifies that the data set can be fully shared 
by any number of users and buffers used for 
direct processing are refreshed for each request. 


This option requires your program to use the ENQ 
and DEQ macros to maintain data integrity while 
sharing the data set. Improper use of the ENQ 
macro can cause problems similar to those 
described under SHAREOPTIONS 3. (CFfor information 
on using aah and DEQ, see System Macros and 


specifies the amount of sharing allowed among systems. 
Job steps of two or more operating systems can gain 
access to the same VSAM data set regardless of the 
disposition specified in each step's DD statement for 
the data set. 


To get exclusive control of the data set's volume, a 
task in one system issues the RESERVE macro. The 
level of cross-system sharing allowed by VSAM applies 
only ina multiple operating system environment. The 
values that can be specified are: 


lL 
Reserved 





Reserved 
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specifies that the data set can be fully shared. co~N 
With this option, each user is responsible for 
maintaining both read and write integrity for the 
data that user's program accesses. 





User programs that ignore write integrity 
guidelines can cause VSAM program checks, 
uncorrectable data set failures, and other 
unpredictable results. This option places heavy 
responsibility on each user sharing the data set. 


specifies that the data set can be fully shared. 
Buffers used for direct processing are refreshed 
for each request. 


This option requires that you use the RESERVE and 
DEQ macros to maintain data integrity while 
sharing the data set. (For information on using 
RESERVE and DEQ, see 

Facilities.) Writing is limited to PUT-update 
and PUT-insert processing that does not change 
the high-used RBA if your program opens the data 
set with DISP=SHR. 


Data set integrity cannot be maintained unless 
all jobs accessing the data set in a cross-system 
environment specify DISP=SHR. Improper use of 
the RESERVE macro can cause problems similar to 
those described under SHAREOPTIONS 3. 


To ensure data integrity in a shared environment, VSAM 
provides users of SHAREOPTIONS 4 (Ccross-region and 
cross~system) with the following assistance: 


° Each PUT request results in the appropriate buffer(s) | 
being written immediately to the VSAM cluster's direct he ae 
access device space (that is, the buffer in the user's 
address space that contains the new or updated data 
record, and the buffers that contain new or updated 
index records when the user's data is key sequenced. ) 


e Each GET request results in all the user's input 
buffers being refreshed. The contents of eo h data and 
index buffer being used by the user's program are 
retrieved from the VSAM cluster's direct access device. 


Abbreviation: SHR 
SPANNED | NONSPANNED 


specifies whether a data record is allowed to cross Seoweees 
interval boundaries. 


SPANNED 
specifies that, if the maximum length of a data record 
Cas specified with RECORDSIZE) is larger than a 
control interval, the record will be contained on more 
than one control interval. This allows VSAM to select 
a control interval size that is optimum for the direct 
access device. 


When a data record that is larger than a control 
interval is put into a cluster that allows spanned 
records, the first part of the record completely fills 
a control interval. Subsequent control intervals are 
filled until the record is written into the cluster. 
Unused space in the record's last control interval is 
not available to contain other data records. 


Abbreviation: SPND 
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NONSPANNED 
mee specifies that the record must be contained in one 
( | control interval. VSAM will select a control interval 
Size that accommodates your largest record. 


Abbreviation: NSPND 
SPEED | RECOVERY 


specifies whether storage allocated to the data component 
is to be preformatted before records are inserted. 
SPEED]RECOVERY applies only to initial loading. 


When you specify RECOVERY, your initial load takes longer 
because the control areas are written initially with 
end-of~-file indicators and again with your data records. 
When you specify SPEED, your initial load 1s quicker. 


SPEED 
specifies that the data component's space is not 
preformatted. Its space might contain data records 
from a previous use of the space, or it might contain 
binary zeros (its contents are unpredictable). 


If the initial load fails, you must load the data 
records again from the beginning, because VSAM is 
unable to determine where your last correctly written 
record is. CVSAM cannot find a valid end-of-file 
indicator when it searches your data records. ) 


RECOVERY 
specifies that the data component's control areas are 
written with records that indicate end of file. When 
a data record is written (during the initial load) 
into a control interval, it is always followed by a 
record that identifies the record that has just been 
( written as the last record in the cluster. 


If the initial load fails, you can resume loading data 
records after the last correctly written data record, 

because an end-of-file indicator identifies it as the 

last record. 


Abbreviation: RCVY 


STAGE |BIND|CYLINDERFAULT 
specifies how a cluster or component that is stored on a 
mass storage volume is to be staged. 


When the cluster or component is not stored on a mass 
storage volume, the attribute is ineffective until the 
direct access storage volume on which the cluster or 
component is stored is converted to a mass storage volume. 
The CONVERTV command used in this conversion is described 
in 057V5_Mass storage stem CMS ervices: Reference 


When one of these parameters iS specified for the data 
component and another parameter is specified for the index 
component, the components are staged separately as 
specified, except when the sequence set of the index 


component is embedded in the data. In that case, the 
parameter specified for the index component applies to both 
components. 

STAGE 


indicates that the cluster or component is to be 
staged from mass storage to a direct access storage 
staging drive when the cluster or component is opened. 
If the cluster or component cannot be staged at open 
time because of heavy staging activity of other 
objects, data is staged as the processing program 
needs it. 
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BIND 
indicates that the cluster or component is not only to 
be staged, but also to be bound; that is, it is to be 
retained on the direct access storage staging drive 
until it is closed. If the cluster or component 
cannot be staged at open time because of heavy staging 
activity of other objects, data is staged as the 
processing program needs it. 


CYLINDERFAULT 
indicates that the cluster or component is not to be 
staged when it is opened, but that data from it is to 
be staged as the processing program needs it. 


Abbreviation: CYLF 
TO( date) | FOR( days) 


specifies the retention period for the cluster being 


defined. If neither TO nor FOR is specified, the cluster 
can be deleted at any time. 


TO( date) 
specifies the date, in the form yyddd, where yy is the 
year and ddd is the number (001 through 365) of the 
co eeu) which the cluster being defined is to be 
ept. 


FOR( days) 
specifies the number of days for which the cluster 
being defined is to be kept. The maximum number that 
can be specified is 9999. If the number specified is 
0 through 1830, the cluster is retained for the number 
of days specified; if the number is between 1831 and 
9999, the cluster is retained through the year 1999. 


days 
can be expressed in decimal (n), hexadecimal 
CX'n'), or binary CB'n') form. 


UNIQUE | SUBALLOC 90 
specifies whether the cluster's components are allocated an 
amount of space from the volume's available space CUNIQUE)D 
or from a VSAM data space's available space 
(SUBALLOCATION). 


UNIQUE 
specifies that a VSAM data space is to be built and 
assigned exclusively to each component of the cluster. 
The data space is created when the cluster is defined. 
The cluster'’s volume(s) must be mounted. VSAM builds 
a DSCB in the volume's table of contents (CVTOC) to 
describe the data space. The name of the data space, 
which is the same as the component's name, is put in 
the DSCB. A subentry is added to the volume entry Cin 
the VSAM catalog) to describe the VSAM data space. 


Abbreviation: UNQ 


SUBALLOCATION 


specifies that space from one of the VSAM data spaces 
on the volume is assigned to the cluster's components. 


Abbreviation: SUBAL 


The space allocation attribute interacts with other DEFINE 
CLUSTER parameters. You should ensure that the space 
allocation attribute you specify for the cluster is 
consistent with other attributes: 


° REUSE: You cannot specify REUSE when you specify UNIQUE 
for a cluster or its components. 
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° KEYRANGES: When UNIQUE is specified, a data space is 
Ne, built and allocated for each key range. Each key range 
1s on a separate volume. 


e VOLUMES: When UNIQUE is not specified, VSAM data space 
must exist on the volume that is to contain the 
cluster's component. When UNIQUE is specified, and 
more than one volume is specified, VSAM must already 
own all the volumes except the first. If there is no 
VSAM space on a volume, you must execute a DEFINE SPACE 
CANDIDATE before your DEFINE UNIQUE. 


UPDATEPW( password) 
specifies an update password for the entry being defined. 
The update password permits read and write operations 
against the entry's records. 


If a read password is the only password specified for the 
object (that is, it is the highest-level password), it 
propagates upward and becomes the password for all higher 
levels. If you specify a higher-level password and do not 
specify an update password, the update password is null. 


Abbreviation: UPDPW 
WRITECHECK | NOWRITEC 


specifies whether the cluster or component is to be checked 
by a machine action called write check when a record is 
written into it. 


WRITECHECK 
specifies that a record is written and then read, 
without data transfer, to test for the data check 
condition. 


( Abbreviation: WCK 


NOWRITECHECK 
specifies that the cluster or component is not to be 
checked by a write check. 


Abbreviation: NWCK 


DATA AND INDEX COMPONENTS OF A CLUSTER 


Attributes can be specified separately for the cluster's data 
and index components. The DATA and INDEX parameters are listed 
at the beginning of this section. These parameters are 
described in detail as parameters of the cluster as a whole. 
Restrictions are noted with each parameter's description. 
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DEFINE CLUSTER EXAMPLES 


| ae, 
Define a Key-Sequenced Cluster Specifying Data and Index Parameters: Example 1 
In this example, a key sequenced cluster is defined. The DATA 
and INDEX parameters are specified and the cluster's data and 
index components are explicitly named. This example assumes 
that, if the cluster is being defined in a VSAM catalog, a VSAM 
data space exists on volume VSERO2. It also assumes that an 
alias name D40 has been defined for the catalog D27UCAT1. This 
Naming convention causes DSG0.MYDATA to be cataloged in D27UCAT1. 
//DEFCLU1L JOB ee 
//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
S/SYSIN DD 4 
DEFINE CLUSTER - 
CNAMECD4G0.MYDATA) - 
VOLUMESCVSERO2) —- 
RECORDSC1000 500)) - 
DATA - 
CNAMECDG0.KSDATA) - 
KEYS(15 0) - 
RECORDSIZEC250 250) - 
FREESPACEC20 10) - 
BUFFERSPACEC25000) ) - 
INDEX - 
CNAMECD40.KSINDEX) - 
IMBED) - | 
CATALOG (CD27UCATI/USERUPPW) 
7X 
The DEFINE CLUSTER command builds a cluster entry, a data entry, 
and an index entry to define the key sequenced cluster GON 
D4G0.MYDATA. The parameters specified for the cluster as a whole : ; 
are: 


° NAME, which specifies that the cluster's name is D40.MYDATA. 


@ VOLUMES, which specifies that the cluster is to reside on 
volume VSERO2. 


° RECORDS, which specifies that the cluster's space allocation 
is 1000 data records. When the cluster is extended, it is 
extended in increments of 500 records. After the space is 
allocated, VSAM calculates the amount required for the index 
and subtracts it from the total. 


In addition to the parameters specified for the cluster as a 

whole, DATA and INDEX parameters specify values and attributes 
that apply only to the cluster's data or index component. The 
parameters specified for the data component of DSG0.MYDATA are: 


° NAME, which specifies that the data component's name is 
D40.KSDATA. 


® KEYS, which specifies that the length of the key field is 15 
bytes and that the key field begins in the first byte Cbyte 
0) of each data record. 


@ ar ata which specifies fixed-length records of 250 
ytes. 


® BUFFERSPACE, which specifies that a minimum of 25 000 bytes 
must be provided for I/O buffers. A large area for I/0 
buffers can help to improve access time with certain types 
of processing. For example, with direct processing if the 7 
high-level index can be kept in virtual storage, access time a ™ 
is reduced. With sequential processing, if enough I/0 ry . 
buffers are available, VSAM can perform a read-ahead thereby a 
reducing system overhead and minimizing rotational delay. 
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@ FREESPACE, which specifies that 20% of each control interval 
on and 10% of each control area are to be left free when 
( | records are loaded into the cluster. After the cluster's 
records are loaded, the free space can be used to contain 
new records. 


The parameters specified for the index component of D40.MYDATA 
are: 


@ NAME, which specifies that the index component's name is 
D40.KSINDEX. 


) IMBED, which specifies that sequence-set index records are 
to be placed in the data component's control areas (the 
sequence-set records will be replicated automatically). 


The parameter which provides the catalog's password is: 


e CATALOG, which specifies the catalog name and its update 
password. This parameter would not be necessary if (1) the 
catalog was not password protected, and (2) D40 was defined 
as the catalog's alias. 


Define a Key-Sequenced Cluster and an Entry-Sequenced Cluster: Example 2 


In this example, two VSAM clusters are defined. The first 
DEFINE command defines a key sequenced VSAM cluster, 
D40.EXAMPLE.KSDS1. The second DEFINE command defines an 
entry-sequenced VSAM cluster, D50.EXAMPLE.ESDS1. In both 
examples, it is assumed that alias names, DG0 and D50, have been 
defined for user catalogs D2/7UCAT1 and D27UCAT2, respectively, 
and that neither user catalog is password-protected. This 
example assumes that VSAM data space that can contain the data 
sets already exists on volumes VSERO2 and VSERO3. 


( 7 //DEFCLU2 JOB sake 

: //STEPI EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD x 


DEFINE CLUSTER - 
CNAMECDGO.EXAMPLE.KSDS1) - 
MODELCDG0.MYDATA) - 
VOLUMESCVSERO2) —- 

NOIMBED 3} 


DEFINE CLUSTER - 
CNAMECD50.EXAMPLE.ESDSI) - 
RECORDS(C100 500) - 
RECORDSIZEC250 250) - 
VOLUMESCVSERO3) - 
NONINDEXED ) 
7% 


The first DEFINE command builds a cluster entry, a data entry, 
and an index entry to define the key sequenced cluster 
D40.EXAMPLE.KSDS1. Its parameters are: 


° NAME, which specifies the name of the Key sequenced cluster, 
DG40.EXAMPLE.KSDS1. The cluster will be defined in the user 
catalog for which D40 has been established as an alias. 


@ MODEL, which identifies D460.MYDATA as the cluster to use as 
a model for DGO.EXAMPLE.KSDS1. The attributes and 
specifications of DGO.MYDATA that are not otherwise 
specified with the DEFINE command's parameters are used to 
define the attributes and specifications of 
D40.EXAMPLE.KSDS1. D40.MYDATA is located in the user 
catalog for which D40 has been established as an alias. 


e VOLUMES, which specifies that the cluster is to reside on 
volume VSERO2. 
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NOIMBED, which specifies that space is not to be allocated 
for sequence-set control intervals within the data 
component's physical extents. 


The second DEFINE command builds a cluster entry and a data 
entry to define an entry-~sequenced cluster, D50.EXAMPLE.ESDSI1. 
Its parameters are: 


NAME, which specifies the name of the entry-sequenced 
cluster, D50.EXAMPLE.ESDS1. The cluster will be defined in 
Sale user catalog for which D50 has been established as an 
alias. 


RECORDS, which specifies that the cluster's space allocation 
is 100 records. When the cluster is extended, it is 
extended in increments of 500 records. 


RECORDSIZE, which specifies that the cluster's records are 
fixed length Cthe average record size equals the maximum 
record size) and 250 bytes long. 


VOLUMES, which specifies that the cluster is to reside on 
volume VSERO3. 


NONINDEXED, which specifies that the cluster is to be an 
entry-sequenced cluster. 


Define a Key-Sequenced Cluster (in a Unique Data Space) in a VSAM Catalog: Example 3 


In this example, a key sequenced cluster is defined. The 
cluster is unique; that is, it is the only cluster in a VSAM 
data space. 


“f/f 
4/ 
Sf 
17 
4/ 


7% 


DEFCLU3S JOB sa 

STEP1 EXEC PGM=IDCAMS 

SYSPRINT DD SYSOUT=A 

VOL4 DD VOL =SER=VSERO4, UNIT=DISK, DISP=OLD 
SYSIN DD % 

DEFINE CLUSTER - 
CNAMECENTRY) - 
RECORDSIZEC80 80) - 
FILECVOL4) - 

KEYSC10 10) - 

VOLUMESCVSERO4) - 

UNIQUE — 

CYLINDERS(C5 10) 3) - 
CATALOGCUSERCAT3) 


The DEFINE CLUSTER command builds a cluster entry, a data entry, 
and an index entry to define the key sequenced cluster ENTRY. 
The DEFINE CLUSTER command also allocates a data space and 
allocates it for the cluster's exclusive use. The command's 
parameters are: 


NAME, which specifies the cluster’s name is ENTRY. 


RECORDSIZE, which specifies that the records are fixed 
length, 80-byte records. 


FILE, which specifies the name of a DD statement that 
describes the cluster's volume and causes it to be mounted. 
The volume must be mounted so that VSAM can record the 
format-1 DSCBs of the key sequenced cluster in the volume's 
VTOC. If FILE is not specified, an attempt is made to 
dynamically allocate the volume. 


KEYS, which specifies that the length of the key field is 10 
bytes and that the key field begins in the llth byte Cbyte 
10) of each data record. 
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8 VOLUMES and UNIQUE, which specify that ENTRY is to reside 
alone in a data space on volume VSEROG. Access method 
services will create two data spaces for the cluster: one 
for the data component, and one for the index. Both data 
spaces are to be on volume VSEROG. This example assumes 
that volume VSER0O4 has enough available space to contain the 
new data space. This example also assumes that either the 
volume's entry is in the MYCAT catalog or that volume VSERO4 
is not owned by a VSAM catalog at the beginning of the job. 


e CYLINDERS, which specifies that five cylinders are allocated 
for the cluster's data space. When the cluster's data or 
index component is extended, the component is to be extended 
in increments of 10 cylinders. 


® CATALOG, which specifies the name of the catalog into which 
the cluster will be defined. In this example, USERCATS is 
not password-protected and an attempt will be made to 
dynamically allocate it. 


Define a Relative Record Cluster in a Catalog: Example 4 


In this example, a relative record cluster is defined. The 
cluster is suballocated (it can reside in a VSAM data space with 
other VSAM objects). Volume VSERO1 does not have to be mounted 
or allocated at this time. 


//DEFCLUG JOB jin% 
//STEPI EXEC PGM=IDCAMS 
“/SYSPRINT DD SYSOUT=A 
S/SYSIN DD % 

DEFINE CLUSTER - 
CNAMECEXAMPLE.RRDS1) -— 
RECORDSIZEC100 100) - 
VOLUMESCVSEROI1) - 
TRACKS(@10 5) - 
NUMBERED) - 

CATALOGCUSERCAT/USERUPPW) 
7% 


The DEFINE CLUSTER command builds a cluster entry and a data 
entry to define the relative record cluster, EXAMPLE.RRDSI in 
the user catalog. The DEFINE CLUSTER command also obtains space 
for the cluster from the VSAM data space on volume VSEROIL, and 
allocates 10 tracks for the cluster's use. The command's 
parameters are: 


® NAME, which specifies that the cluster's name is 
EXAMPLE.RRDS1. 


e RECORDSIZE, which specifies that the records are fixed 
length, 100-byte records. Average and maximum record length 
must be equal for a relative record data set. 


e VOLUMES, which specifies that the cluster is to reside on 
volume VSERO1]L. This example assumes that the volume is 
already cataloged in the user catalog, USERCAT. 


¢ TRACKS, which specifies that ten tracks are to be allocated 
for the cluster. When the cluster is extended, it is to be 
extended in increments of 5 tracks. 


e NUMBERED, which specifies that the cluster's data 
organization is to be relative record. 


6 CATALOG, which supplies the user catalog's update password, 
USERUPPW. 
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Define a Reusable Entry-Sequenced Cluster in a Catalog: Example 5 


In this example, a reusable entry-sequenced cluster is defined. e 
The cluster can be used as a temporary data set. Each time the aed 
cluster is opened, its high-used RBA can be reset to zero. The 
cluster is suballocated (that is, it can reside in a VSAM data 

space with other VSAM objects). 


//DEFCLU5 JOB ‘ 
//STEPI EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
S/SYSIN DD % 
DEFINE CLUSTER - 
CNAMECEXAMPLE.ESDS2) - 
RECORDSIZEC2500 3000) - 
SPANNED - 
VOLUMESCVSERO3) - | 
CYLINDERSC2 1) - | 
NONINDEXED - 
REUSE - 
MASTERPWCESD2MRPW) —- 
UPDATEPNCESD2UPPW) 9) - 
CATALOGCD27UCAT 2“ USERMRPW) 
7% 


The DEFINE CLUSTER command builds a cluster entry and a data 
entry to define the entry-~sequenced cluster, EXAMPLE.ESDS2. The 
DEFINE CLUSTER command also obtains space for the cluster from 
one of the Class 1 VSAM data spaces on volume VSERO3, and 
assigns ten tracks for the cluster's use. VSERO3 does not have 
to be mounted or allocated at this time. The command's 
parameters are: 


@ NAME, which specifies that the cluster's name is 
EXAMPLE.ESDS2. 


e RECORDSIZE, which specifies that the records are | 
variable-length, with an average size of 2500 bytes and a ee Sh 
naximum size of 3000 bytes. 


e SPANNED, which specifies that data records can cross control 
interval boundaries. 


e VOLUMES, which specifies that the cluster is to reside on 
volume VSERO3. This example assumes that the volume is 
already cataloged in the user catalog, D27UCAT2. 


e CYLINDERS, which specifies that two cylinders are to be 
allocated for the cluster's space. When the cluster is 
extended, it is to be extended in increments of one 
cylinder. 


e NONINDEXED, which specifies that the cluster's data 
organization is to be entry sequenced. This parameter 
overrides the INDEXED parameter. 


e REUSE, which specifies that the cluster is to be reusable. 
Each time the cluster is opened, its high-used RBA can be 
reset to zero and it is effectively an empty cluster. 


| 

e MASTERPW and UPDATEPW, which specifies the master password, 
a eat and the update password, ESD2UPPW, for the | 
cluster. 


e CATALOG, which specifies that the cluster is to be defined 
ina ouser catalog, D27UCAT2. The example also supplies the 
user catalog's master password, USERMRPHW. 
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Define a Key-Sequenced Cluster in a Catalog: Example 6 


In this example, a key sequenced cluster is defined. In other 
examples, an alternate index is defined over the cluster, and a 
path is defined that relates the cluster to the alternate index. 
The cluster, its alternate index, and the path entry are all 
defined in the same catalog, USERRCAT. 


“//DEFCLU6 JOB a 
//STEPL EXEC PGM=IDCAMS 
“/7SYSPRINT DD SYSOUT=A 
S/SYSIN DD % 
DEFINE CLUSTER - | 
CNAMECEXAMPLE.KSDS2)) - 
DATA - 
(MASTERPNCDAT2MRPW) - 
UPDATEPNCDAT2UPPW) —- 
READPNCDAT2RDPW) - 
RECORDS(500 100) - 
EXCEPTIONEXITCDATEXIT) - 
ERASE - 
FREESPACEC20 10) - 
KEYS(6 4) - 
RECORDSIZEC80 100) - 
VOLUMESCVSERO1) )D - 
INDEX - 
CMASTERPWCIND2MRPW) —- 
UPDATEPWCIND2UPPW) - 
READPWCIND2RDPW) - 
RECORDS(300 300) - 
IMBED - 
VOLUMESCVSEROL1) ) - 
CATALOGCUSERCAT/USERUPPW) 
7% 


The DEFINE CLUSTER command builds a cluster entry, a data entry, 
and an index entry to define the key sequenced cluster, 
EXAMPLE.KSDS2. The DEFINE CLUSTER command also obtains space 
for the cluster from one of the VSAM data spaces on volume 
VSERO1, and allocates space separately for the cluster's data 
and index components. Because the cluster is being defined into 
a recoverable catalog, an attempt will be made to dynamically 
allocate the catalog recovery area on VSEROI. 


The command's parameter that applies to the cluster is: 


® NAME, which specifies that the cluster'’s name is 
EXAMPLE.KSDS2. 


The command's parameters that apply only to the cluster's data 
Suelo are enclosed in the parentheses following the DATA 
eyword: 


e MASTERPW, UPDATEPW, and READPWN, which specify the data 
component's master password, DAT2MRPW, update password, 
DATZUPPW, and read password, DATZRDPW. 


° RECORDS, which specifies that an amount of tracks equal to 
at least 500 records is to be allocated for the data 
component's space. When the data component is extended, it 
1s to be extended in increments of tracks equal to 100 
records. 


@ EXCEPTIONEXIT, which specifies the name of the exception 
exit routine, DATEXIT that is to be processed if an I/0 
error occurs while a data record is being processed. 


9 ERASE, which specifies that the cluster's data is to be 
eee with binary zeros) when the cluster is 
eleted. 


° FREESPACE, which specifies the amounts of free space to be 
left in the data component's control intervals (20%) and the 
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control areas (10% of the control intervals in the control 
area) when data records are loaded into the cluster. 


e KEYS, which specifies the location and length of the key 
field in each data record. The Key field is 6 bytes long 
and begins in the 5th byte Cbyte 4) of each data record. 


e RECORDSIZE, which specifies that the cluster's records are 
variable length, with an average size of 80 bytes anda 
maximum size of 100 bytes. 


e VOLUMES, which specifies that the cluster is to reside on 
volume VSERO1. This example assumes that the volume is 
already cataloged in the catalog, USERCAT. 


The command's parameters that apply only to the cluster's index 
eae are enclosed in the parentheses following the INDEX 
eyword: 


e MASTERPW, UPDATEPW, and READPW, which specifies the index 
component's master password, IND2MRPW, update password, 
IND2UPPW, and read password, IND2RDPW. 


e RECORDS, which specifies that an amount of tracks equal to 
at least 300 records is to be allocated for the index 
component's space. When the index component is extended, it 
is gee extended in increments of tracks equal to 300 
records. 


e IMBED, which specifies that the index's sequence set records 
are to be placed in the data component's control areas (the 
sequence set records will be replicated automatically). 


e VOLUMES, which specifies that the index component is to 
reside on volume VSEROI1. 


The CATALOG parameter supplies the catalog's update password. 


Define an Entry-Sequenced Cluster Using a Model: Example 7 


In this example, two entry-~sequenced clusters are defined. The 
attributes of the second cluster defined is modeled from the 
first cluster. 


//DEFCLU7 JOB... 
//STEP 1 EXEC  PGM=IDCAMS 


“/STEPCAT DD DSNAME=USERCAT4, DISP=SHR 
//7SYSPRINT DD SYSOUT=A 
ZASYSIN DD K 
DEFINE CLUSTER - 
CNAMECGENERIC.A.BAKER) ~ 
VOLUMESCVSERO2) - 


RECORDS(100 100) - 

RECORDSIZEC80 80) - 

NONINDEXED ) - 
CATALOGCUSERCAT4/USERMRPW) 


DEFINE CLUSTER - 
CNAMECGENERIC.B.BAKER) — 
MODEL CGENERIC.A.BAKER USERCAT4)) - 
CATALOGCUSERCAT4/USERMPRW) 
7K 


Job control language statement: 


e STEPCAT DD, which makes a catalog available for this job 
step: USERCATS. 


The first DEFINE CLUSTER command defines an entry~sequenced 
cluster, GENERIC.A.BAKER. Its parameters are: 


@ NAME, which specifies the name of the entry-sequenced 
cluster, GENERIC.A.BAKER. 
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VOLUMES, which specifies that the cluster is to reside on 
volume VSERO2. 


RECORDS, which specifies that the cluster's space allocation 
is 100 records. When the cluster is extended, it is 
extended in increments of 100 records. 


RECORDSIZE, which specifies that the cluster's records are 
fixed length (the average record size equals the maximum 
record size) and 80 bytes long. 


NONINDEXED, which specifies that the cluster is entry 
sequenced. 


CATALOG, which specifies that the cluster is to be defined 
eneaene catalog. The master password of USERCATS is 


The second DEFINE CLUSTER command uses the attributes and 
specifications of the previously defined cluster, 
GENERIC.A.BAKER, as a model for the cluster still to be defined, 
GENERIC.B.BAKER. Its parameters are: 


NAME, which specifies the name of the entry-~sequenced 
cluster, GENERIC.B.BAKER. 


MODEL, which identifies GENERIC.A.BAKER, cataloged in user 
catalog D27UCAT1, as the cluster to use as a model for 
GENERIC.B.BAKER. The attributes and specifications of 
GENERIC.A.BAKER that are not otherwise specified with the 
DEFINE command's parameters are used to define the 
attributes and specifications of GENERIC.B.BAKER. 

CATALOG, which specifies that the cluster is to be defined 
neecuceg catalog. The master password of USERCATS is 
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DEFINE GENERATIONDATAGROUP 


The DEFINE GENERATIONDATAGROUP command creates a catalog entry | 
for a generation data group. The format of this command is: S/ 


DEFINE GENERATIONDATAGROUP 
(NAMECe ) 
LIMITClimit } 
[EMPTY | NOEMPTY] 
COWNER( ownerid)1. 


[SCRATCH INOSCRATCH] 
[TO( date) | FOR(days)]) 





[CATALOG( catnamel Zpasswordi)1 
DEFINE can be abbreviated: DEF 


DEFINE GENERATIONDATAGROUP PARAMETERS 


Required Parameters 


GENERATIONDATAGROUP 


specifies that a generation data group entry is to be 
defined. 


Abbreviation: GDG 
NAME (entryname) 


specifies the name of the generation data group that is 
being defined. 


LIMIT( Limit) ‘ 
specifies the maximum number, from 1 to 255, of generation Oe? 
data sets that can be associated with the generation data 
group to be defined. number can be expressed in decimal 
(nd), hexadecimal (X'n'), or binary CB'n') form. 


Abbreviation: LIM 


Optional Parameters 


CATALOG( catnamel/password] } 
identifies the catalog in which the generation data group 
is to be defined. If the catalog'’s volume is physically 
mounted, it is dynamically allocated. The volume must be 
mounted as permanently resident or reserved. For 
information about the order in which a catalog is selected 
when the catalog's name is not specified, see "Order of 
Catalog Selection for DEFINE™ on page 1 


specifies the name of the catalog. 


specifies the catalog's password. If the catalog is 
password protected, you must supply the update- or 
higher-level password. RACF: The update or higher 
RACF authority to the catalog is required. 


Abbreviation: CAT 
EMPTY | NOEMPTY 


specifies what action is to be taken when the maximum 7 
number of generation data sets for the generation data eo 
group has been reached and another generation data set is “ 
to be cataloged. The disposition of the data set's DSCB in ca 
| the volume's VTOC is determined with the SCRATCH|NOSCRATCH 
parameter. 
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EMPTY | : 
saa specifies that all the generation data sets are to be 
- uncataloged when the maximum is reached Ceach data 
set's non-VSAM entry is automatically deleted from the 
catalog). 
Abbreviation: EMP 
NOEMPTY 


specifies that only the oldest generation data set is 
to be uncataloged when the maximum is reached. 


Abbreviation: NEMP 
OWNER( ownerid) 


identifies the generation data set's owner. 


Note to TSO users: If the owner is not identified with the 
OWNER parameter, the TSO userid is the default ownerid. 


SCRATCH | NOSCRATCH 


specifies whether a generation data set's DSCB is to be 
deleted from the volume's VTOC when the data set is 
uncataloged (that is, when its entry is deleted from the 
catalog automatically, as a result of EMPTY|NOEMPTY, or 
specifically, as a result of a user issued DELETE request). 
The user can override the SCRATCH|NOSCRATCH attribute when 
issuing the DELETE command. 


SCRATCH 

specifies that the generation data set's DSCB is to be 
deleted from the volume's VTOC when the generation 
data set is uncataloged. Direct access device space 
management CDADSM) removes the data set's DSCB from 

| the VTOC, erases the data set's space on the volume, 

vets and makes the space available to other system users. 

( The generation data set ceases to exist. 


Note: On MSS volumes, even if SCRATCH is specified, 
the data set will not be scratched when it is 
automatically uncataloged. 


Abbreviation: SCR © 


NOSCRATCH 

specifies that the generation data set's DSCB is not 
to be removed from the volume's VTOC when the 
generation data set is uncataloged. The data set's 
DSCB in the volume's VTOC is left intact and can be 
used to locate the data set. However, your program 
can process the data set as it processes any other 
non-VSAM data sets-——that is, by using a JCL DD 
statement to describe the data set and allocate it. 


Abbreviation: NSCR 
TO( date) [FOR( days) 


specifies the retention period for the generation data 
group being defined. 


TO(date) 
specifies the date, in the form yyddd, where yy is the 
year and ddd is the number (001 through 365) of the 
day through which the generation data group being 
defined is to be Kept. 
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DEFINE GENERATIONDATAGROUP 
 FOR( days) | 


specifies the number of days for which the generation ff ™ 
data group being defined is to be kept. This value e 
can be expressed in decimal (n), hexadecimal (X'n'"), cus 
or binary CB'n'"). 
The maximum number that can be specified is 9999. If 
the number specified is 0 through 1830, the generation 
data group is retained for the number of days 
specified; if the number is between 1831 and 9999, the 
generation data group is retained through the year 
1999. If neither TO nor FOR is specified, the 
generation data group can be deleted at any time. 

DEFINE GENERATIONDATAGROUP EXAMPLE 

Define a Generation Data Group and a Generation Data Set within It: Example 1 

In this example, a generation data group is defined in the 

master catalog. Next, a generation data set is defined within 

the generation data group by using JCL statements. 
//DEFGDG1 JOB iss 
//STEPI1 EXEC PGM=IDCAMS 
//GDGMOD DD DSNAME=GDG01,DISP=C, KEEP), 
// SPACE=CTRK,(C0)),UNIT=DISK, VOL=SER=VSERO3, 
// DCB=CRECFM=FB, BLKSIZE=2000, LRECL=100) 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD xX 
DEFINE GENERATIONDATAGROUP - 

CNAMECGDGOL1) - 

EMPTY - 

NOSCRATCH - 

LIMITC255) ) 
7X 
//DEFGDG2 JOB ere 
//STEPI EXEC PGM=IEFBR14 
//GDGDD1 DD DSNAME=GDG01(4+1),DISP=CNEW,CATLG), 
// SPACE=C(CTRK,€10,5)),VOL=SER=VSERO03, 
Sf UNIT=DISK 
Z/SYSPRINT DD SYSOUT=A 
//S5YSIN DD x 
/X% 

Job control language statement: 

° GDGMOD DD, which describes the generation data group. When 
the scheduler processes the DD statement, no space is 
allocated to GDGOl. 

The model DSCB must exist on the generation data group's 
catalog volume. 

Because no catalog was specified with a JOBCAT or STEPCAT DD 

statement or with the CATALOG parameter, VSAM assumes all 

entries built for this command sequence are to be cataloged in 
the master catalog. 

The DEFINE GENERATIONDATAGROUP command defines a generation data 

group base catalog entry, GDGO1l. Its parameters are: 

6 NAME, which specifies the name of the generation data group, 
GDGO1. Each generation data set in the group will have the 
name GDGO1.GxxxxVyy, where "xxxx™ is the generation number 
and "yy" is the version number. 

e EMPTY, which specifies that all data sets in the group are —_ 
to be uncataloged by VSAM when the group reaches the maximum 4 oY 


number of data sets (as specified by the LIMIT parameter) 
and one more generation data set is added to the group. 
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e NOSCRATCH, which specifies that when a data set is 
uncataloged, its DSCB is not to be removed from its volume's 
VTOC. Therefore, even if a data set is uncataloged, its 
records can be accessed when it is allocated to a job step 
with the appropriate JCL DD statement. 





® LIMIT, which specifies that the maximum number of generation 
data sets in the group is 255. The LIMIT parameter is 
required. 


The second job, DEFGDG2, is used to allocate space and catalog a 
generation data set in the newly defined generation data group. 


Job control statement: 


e GDGDD1 DD, which specifies a generation data set in the 
generation data group. 
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The DEFINE NONVSAM command defines a catalog entry for a 
non-VSAM data set. The format of this command is: 


DEFINE NONVSAM 
(NAMELe 


entryname) 
DEVICETYPES(devtypel devtvype...1) 
VOLUMES(volser[ volser...1) 


[FILESEQUENCENUMBERS(numberlf hnumber..1)] 
LOWNER( ownerid)] | 
[TO( date) | FOR(davs)]) 





[CATALOG( catnamel/password!])] 


DEFINE can be abbreviated: DEF 


DEFINE NONVSAM PARAMETERS 


Required Parameters 


NONVSAM 
specifies that a non-VSAM data set is to be defined. 


Abbreviation: NVSAM 


NAME (entryname) 
specifies the name of the non-VSAM data set being defined. 
The entryname is the name that appears in the catalog; it 
is the name used in all future references to the data set. 
The entryname must be unique within the catalog in which it 
is defined. 


You identify a generation data set with its generation data 
group name followed by the data set's generation and 
version numbers (GDGname.GxxxxVyy). Relative generation 
numbers (Cthat is, GDGname(+1)) cannot be used with the 
entryname when you use the DEFINE NONVSAM command to 
catalog a generation data set and attach it to a generation 
data group. If the containing catalog is RACF defined, 
then the update or higher RACF authority to the generation 
data group is required. 


DEVICETYPES(devtypel devtvype...1)} 
specifies the device types of the volumes containing the 
non-VSAM data set being defined. If the non-VSAM data set 
resides on different device types, the device types must be 
specified in the same order as the volume Serial numbers 
listed in the VOLUMES parameter. 


You can specify a device type for any device that is 
supported by your system. You can specify a generic device 
type (that is, 3380, 3375, 3330). You can only specify a 
device type named by the user (such as SYSDA or TAPE) if 
the name was established in the system device name table 
during system generation. 


CAUTION: When a device type named by the user is specified, 
the device type put in the catalog record is the unique 
device type generated for that unit name in the system 
device name table during SYSGEN. This unique device type 
is a function of the order of that unit name in the Stage l 
SYSGEN deck. Allocation errors will result if a data set, 
cataloged with a device type named by the user, is referred 
to on a system where SYSGEN generated the unit names 
differently. 


If the catalog is shared between systems, this device type 
may be different if the unit names were not ordered the 
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same in all Stage 1 SYSGEN decks. An I/0 GEN may also 
change this device type if the order of unit names in the 
Stage 1 SYSGEN deck is different. 


See the discussion of the SCRATCHINOSCRATCH option of the 
DELETE command for a restriction on deleting data sets that 
have been defined with a device type named by the user. 


If you expect to change the device type of the system 
residence volume, you can code DEVICETYPES(C0000) and this 
field will be resolved at SUPERLOCATE, LOCATE, and DELETE 
time to the device type. This will allow you to use the 
non-VSAM data sets without having to recatalog them to 
point to the new volume. When you code DEVICETYPES(C0000) 
you Hiri also code VOLUMES(C *X¥**¥x*X"), or an error will 
result. 


Abbreviation: DEVT 
VOLUMES(volserlf volser...]) 


specifies the volumes to contain the non-VSAM data set. In 
a system with the Mass Storage System, a non-VSAM data set 
can be defined on a mass storage volume. You can specify 
more than one volume serial number if the data set resides 
on many volumes. 


If the data set resides on magnetic tape and more than one 
file belongs to the data set on a single tape volume, you 
must repeat the volume's serial number in order to maintain 
a one to one correspondence between the volume serial 
numbers and the file sequence numbers. 


For example, if your non-VSAM data set is contained in the 
oe re files of magnetic tape volume TAPE10, you 
specify: 


DEVICETYPESC3400-6 3400-6 3900-6) - 
VOLUMESCTAPE1O TAPE10 TAPEI10) - 
FILESEQUENCENUMBERSC1 2 3) - 


If you expect to change the serial number of the system 
residence volumes, you can code VOLUMESC "XXXXx*XX') and this 
field will be resolved at SUPERLOCATE, LOCATE, and DELETE 
time to that number. This will allow you to use the 
non-VSAM data sets without having to recatalog them to 
point to the new volume. 


RACF commands can be used to specify an ERASE attribute in 
a generic or discrete profile for a non-VSAM data set. Use 
of this attribute renders all allocated DASD tracks 
unreadable before space on the volume 1s made available for 
reallocation. Refer to the appropriate RACF publications 
for information about how to specify and use this facility. 


Abbreviation: VOL 


CATALOG(catnamel/password] ) 
identifies the catalog in which the non-VSAM data set is to 
be defined. 


For information about the order in which a catalog is 


selected when the catalog's name is not specified, see 
"Order of Catalog Selection for DEFINE” on page 16 


specifies the name of the catalog in which the entry 
is to be defined. 


specifies the catalog's password. If the catalog is 
password protected, you must supply the update- or 
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higher-level password. RACF: The update or higher 
RACF authority to the catalog is required. 


Abbreviation: CAT 


FILESEQUENCENUMBERS(numberl number...1]) 
specifies the file sequence number of the non-VSAM data set 
being defined. This number indicates the position of the 
file being defined with respect to other files of the tape. 
If the data set spans volumes, the file sequence number on 
each volume must be specified. The numbers must be 
specified in the same order as the volumes in the VOLUMES 
parameter. 


For example, if your non-VSAM data set is contained in the 
oe nee files of magnetic tape volume TAPE10, you 
specify: 


DEVICETYPES(3400-6 3400-6 3400-6) - 
VOLUMESCTAPE10 TAPE10 TAPE10) - 
FILESEQUENCENUMBERS(1 2 3) - 


can be expressed in decimal (n), hexadecimal (X'n'), 
or binary CB*n*) form. 


Abbreviation: FSEQN 
OWNER (ownerid) 


identifies the owner of the non-VSAM data set. 


Note to TSO users: If OWNER is not specified, the TS0 
userid is the default ownerid. 


TO( date) [FOR( days) 
specifies the retention period for the non-VSAM data set 
being defined. The non-VSAM data set is not automatically 
deleted when the expiration date is reached. When you do 
not specify a retention period, the non-VSAM data set can 
be deleted at any time. The expiration date will be placed 
in the catalog, but not in the format-1l DSCB. 


TO( date) 
specifies the date, in the form yyddd, where yy is the 
year and ddd is the Julian date (001, for January Il, 
through 365, for December 31), through which the 
non-VSAM data set is to be Kept before it is allowed 
to be deleted. 


FOR( days) 
specifies the number of days for which the non-VSAM 


data set is to be kept before it is allowed to be 
deleted. 


The maximum number that can be specified for days is 
9999. If the number specified is 0 through 1830, the 
retention period is the number of days specified. If 
the number specified is between 1831 and 9999, the 
retention period is through the year 1999. days can 
be expressed in decimal (n), hexadecimal (X'n"), or 
binary (CB'n') form. 
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DEFINE NONVSAM EXAMPLE 





DEFINE NONVSAM 


Define a Non-VSAM Data Set: Example 1 


In this example, two existing non-VSAM data sets are defined in 
a catalog, USERCAT4. The DEFINE NONVSAM command cannot be used 
to create a non-VSAM data set because the command does not 
allocate space. 


//DEFNVS JOB oe 
//STEPI EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
“/SYSIN DD 


% 

DEFINE NONVSAM ~- 
CNAMECEXAMPLE.NONVSAM) - 
DEVICETYPES(3380) - 
VOLUMESCVSERO2) ) - 

CATALOGCUSERCAT4/USERMRPW) 


DEFINE NONVSAM - 
CNAMECEXAMPLE.NONVSAM2) - 
DEVICETYPES(C3380) - 
VOLUMESCVSERO2) 3) - 

CATALOGCUSERCAT4/USERMRPW) 


Both DEFINE NONVSAM commands define a non-VSAM data set in 
catalog USERCAT¢?. The DEFINE NONVSAM commands! parameters are: 


NAME, which specifies the name of the non-VSAM data sets, 
EXAMPLE.NONYSAM and EXAMPLE.NONVSAM2. 


DEVICETYPES, which specifies the type of device that 
contains the non-VSAM data sets, an IBM 3380-1 Direct Access 
Storage Device. 


VOLUMES, which specifies the volume that contains the 
non-VSAM data sets, VSERO2. 


CATALOG, which identifies the catalog that is to contain the 


non-VSAM entries, USERCAT4, and its update- or higher-level 
password, USERMRPW. 
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DEFINE PAGESPACE 


The DEFINE PAGESPACE command defines an entry for a page space = * 
data set. The format of this command is: es 


DEFINE PAGESPACE 
(NAME Centryname) 
{CYLINDERS (primary) | 
RECORDS (primary) | 
TRACKS (primary }4 
VOLUME(volser ) 
[ATTEMPTS (number [2)1 
LAUTHORIZATIONCentrypointt string])1 
[CODE( code) 1 
PCONTROLPWCpassword) 1 
[FILE( 
tHASTERPW password) 
[MODEL Centrynamel /password] 
[ catnamel/password]1)1 
[TOWNER( ownerid)] 
PREADPW (password) ] 
[SWAP |NOSWAP 1] 
[(TO( date) |FOR(days)1 
[UNIQUE | SUBALLOCATION] 
LUPDATEPW( password)1]) 


[CATALOG( catnamel/password])}1 





DEFINE can be abbreviated: DEF 


DEFINE PAGESPACE PARAMETERS 


Required Parameters 


red 


PAGESPACE 
specifies that a page space is to be defined. 


Abbreviation: PGSPC 
NAME Centryname) 


specifies the name of the page space being defined. 


CYLINDERS (primary) | 
RECORDS (primary) j 

TRACKS (primary) 
specifies the amount of space that is to be allocated by 
tracks, cylinders, or number of records. If RECORDS or 
TRACKS is specified, the quantity specified is rounded up 
to the nearest cylinder and the space is allocated in 
cylinders. 


To determine the exact amount of space allocated, list the 
page space's catalog entry, using the LISTCAT command. 


If you do not specify the MODEL parameter, you must specify 
one, and only one, of the following parameters: CYLINDERS, 
RECORDS, or TRACKS. 


When you specify UNIQUE, and the page space's data space is 
the first data space on the volume that belongs to a 
recoverable catalog, an additional amount (the equivalent 
of one cylinder) is allocated for the recovery area data 


space. 

primary ae 
specifies the amount of space that is to be allocated ‘ae 
to the page space. After the primary extent is full, ‘e / 


the page space is full. The page space cannot extend 
onto secondary extents. 
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primary can be expressed in decimal (n), hexadecimal 
(X'n"), or binary (CB'n') form. 


Abbreviations: CYL, REC, and TRK 


VOLUMES(volser) 
specifies the volume that contains the page space. 


In a system with the Mass Storage System, a page space 
cannot reside on a mass storage volume. 


Unless you specify the MODEL parameter, you must specify 
the VOLUMES parameter. 


The VOLUMES parameter interacts with other DEFINE PAGESPACE 
parameters. You should ensure that the volume(Cs) you 
specify for the page space are consistent with the page 
space's other attributes: 


° SUBALLOCATION: If suballocation is specified, the 
volume must contain a VSAM data space. 


e CYLINDERS, RECORDS, TRACKS: The volume must contain 
enough unallocated space to satisfy the page space's 
space requirement. 


e FILE: The volume information supplied with the DD 
statement pointed to by FILE must be consistent with 
the information specified for the page space. 


e CATALOG: If the page space is suballocated, the data 
space on the volume must have been defined in the same 
catalog as the page space, and must be owned by the 
catalog. 


Abbreviation: VOL 


Optional Parameters 
CATALOG ( catnamel /password]) 


specifies the name and password of the catalog in which the 
page space is to be defined. 


When the CATALOG parameter identifies a user catalog, you 
must also supply a STEPCAT or JOBCAT DD statement to 
describe and allocate the user catalog. For information 
about the order in which catalogs are selected, see "Order 
of Catalog Selection for DEFINE™ on page 16. 


ca tname 


specifies the name of the catalog. 


specifies a password. If the catalog is 
password-protected, you must supply the catalog's 
update- or higher-level password. If no password is 
specified, VSAM may ask the operator or TSO terminal 
user for the correct password. RACF: The update or 
higher RACF authority to the catalog 1s required. 


Abbreviation: CAT 
ATTEMPTS (number 12) 


specifies the maximum number of times the operator or TSO 
terminal user can try to enter a correct password in 
response to a prompting message. A prompting message is 
issued only when the user has not already supplied the 
appropriate password. When you define a page space, you 
should specify ATTEMPTS(C0), so that the operator is not 
prompted and is not allowed to enter a password from the 
console. This parameter only has effect when the entry's 
master password is not null. 
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can be any number from 0 to 7. number can be 
expressed in decimal (n), hexadecimal (X'n"), or 
binary CB'n'") form. 


Note to TSO users: At a TSO terminal, the logon password 
is checked first before the user is prompted to supply a 
password for the page space. Checking the logon password 
counts as one attempt to obtain a password. If ATTEMPTS is 
not specified, the user has one attempt to supply the page 
space's password, because the default is 2. 


Abbreviation: ATT 
AUTHORIZATION(entryvpointl( string]) 


specifies that a user-~security-verification routine CUSVR) 
is available for additional security verification. When a 
protected page space is accessed and the user supplies a 
correct password other than the page space's master 
password, the USVR receives control. For details on the 
USVR, see ini j Guide. 


If a USVR is loaded from an unauthorized library during 
access method services processing, an abnormal termination 
will occur. See "Authorized Program Facility” in 


This parameter only has effect when the entry's master 
password is not null. 


specifies the name of the user's~security~verification 
routine. 


specifies information to be passed on to the USVR when 
it receives control to verify authorization. 


Abbreviation: AUTH 
CODE(code) 


specifies a code name for the page space. If an attempt is 
made to access a password-protected entry without a 
password, the code name is used in a prompting message; the 
code enables the operator or TSO terminal user to be 
prompted for the password without disclosing the name of 
the entry. If code is not specified and an attempt is made 
to access a page space entry that is password-protected 
without supplying a password, the operator or TSO terminal 
user will be prompted with the name of the entry. 


This parameter only has effect when the cluster's or 
component's master password is not null. 


CONTROLPW( password) 
specifies a control-level password for the page space. 
Because the page space is a system data set, it cannot be 
opened or used by a user's program. 


If a read or update password is the only password specified 
for the page space, it (the highest-level password) 
propagates upward and becomes the password for all higher 
unspecified levels. 


The passwords are cataloged in both the page space entry 
and its data component's entry. The system automatically 
prevents users from accessing page spaces and their data 
components. 


Abbreviation: CTLPW 
FILE(ddname) 


specifies the name of the DD statement that identifies the 
device and volume to be allocated to the page space. 


124 MVS/XA VSAM Catalog: Access Method Services Reference 





‘e__/ 

















DEFINE PAGESPACE 


If the page space is unique, and if the FILE parameter is 
not specified and the volume is physically mounted, the 
volume identified with the VOLUME parameter is dynamically 
allocated. The volume must be mounted as permanently 
resident or reserved. 


MASTERPW( password) 
specifies a master password for the page space. The master 
password allows all access method services operations 
against the page space entry. The AUTHORIZATION, CODE, and 
ATTEMPTS parameters have no effect unless the entry has a 
master password associated with it. If MASTERPW is not 
specified, the highest level password specified becomes the 
password for all higher levels. Because the page space is 
a system data set, it cannot be opened or used by a user's 
program. 


The passwords are cataloged in both the page space entry 

and its data component's entry. The system automatically 
prevents users from accessing page spaces and their data 

components. 3 


Abbreviation: MRPW 


MODEL Centrynamel/password] 
[ catname[/password1]]) 
specifies that an existing page space entry is to be used 
as a model for the entry being defined. It is possible to 
use an already defined page space as a model for another 
page space. When one entry 1s used as a model for another, 
its attributes are copied as the new entry is defined. 


You may use some attributes of the model and override 
others by explicitly specifying them in the definition of 
the page space. If you do not want to add or change any 
attributes, specify only the entry type Cpage space) of the 
model to be used and the name of the entry to be defined. 


specifies the name of the page space entry to be used 
as a model. 


password | 
specifies a password. If the entry to be used as a 
model is password-protected and is cataloged ina 
password-protected catalog, a password is required. 


If the protection attributes are to be copied, 
substitute the master password of either the entry 
being used as a model (following entryname) or the 
catalog in which the entry being used as a model is 
defined (following catname). 


lf you specify both passwords, the catalog's password 
is used. If protection attributes are not to be 
copied, any password can be used. RACF: The alter 
RACF authority to the model or catalog is required. 


specifies the name of the catalog in which the entry 
to be used as a model is defined. You identify the 
catalog that contains the model entry for either of 
these cases: 


® You specify the catalog's password instead of the 
model entry's password. 


® The model entry's catalog is not identified with a 
JOBCAT or STEPCAT DD statement, and is not the 
master catalog. 


OWNER( ownerid) 
specifies the identification of the owner of the page 
space. 
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READPW (password } 


specifies a read-level password for the page space. 
, Because the page space is a system data set, it cannot be 
i e opened or used by a user's program. 


The passwords are cataloged in both the page space entry 

and its data component's entry. The system automatically 

prevents users from accessing page spaces and their data 
components. | 


Abbreviation: RDPW 
SWAP | NOSWAP 


specifies whether page space will be defined for local 
system queue area (LSQA) pages or for pageable private area 
pages. (CAuxiliary storage management separates private 
area address space pages into LSQA pages and pageable 
private area pages.) 


SWAP 
specifies that the page space is a high-speed data set 
used during a swap operation to store and retrieve the 
set of LSQA pages owned by an address space. 


NOSWAP ; 
indicates that the page space is a conventional page 
space used to record pageable private area pages. 


Abbreviation: NSWAP 
TO( date) | FOR( days) 


specifies the retention period for the page space. 


If neither TO nor FOR is specified, the page space can be 
deleted at any Pees 


TO(date) 
specifies the date, in the form yyddd, where yy is the 
year and ddd is the number (001 through 365) of the 
uae which the cluster being defined is to be 
ept. 


FOR( days) 
specifies the number of days for which the page space 
is to be kept. The maximum number that can be 
specified is 9999. If the number specified is 0 
through 1830, the page space is retained for the 
number of days specified; if the number is between 
1831 and 9999, the page space is retained through the 
year 1999. 


days 


can be expressed in decimal (n), hexadecimal 
CX'n"), or binary (B'n') form. 
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DEFINE PAGESPACE 


UNIQUE | SUBALLOCATION 
specifies whether the page space is allocated an amount of 
space from the volume's available space CUNIQUE) or from a 
previously defined VSAM data space (SUBALLOCATION). 


UNIQUE 
specifies that the page space is to be allocated a 
VSAM data space of its own. VSAM generates a name for 
the data space and builds a format-1l DSCB in the 
volume's VTOC to describe it. 





Auxiliary storage management recommends that UNIQUE be 
used for page space data sets. This will cause VSAM 
to allocate a single nonshared data space for the page 
data set. Space from another data space will not be 
used, eliminating one of the possibilities for 
multiple extent data sets that will cause auxiliary 
storage management performance degradation. 


Abbreviation: UNQ 


SUBALLOCATION 
specifies that the name of the data space, not of the 
page space, is to appear in the VTOC. A data space 
must have been defined on the volume on which the page 
space is defined. 


Abbreviation: SUBAL 
UPDATEPW( password) 


specifies an update-level password for the page space. 
Because the page space is a system data set, it cannot be 
opened or used by a user's program. 


If a read password is the only password specified for the 
- page space (that is, it is the highest-level password), it 
a propagates upward and becomes the password for all higher 

levels. If you specify a higher-level password and do not 

specify an update password, the update password is null. 


The passwords are cataloged in both the page space entry 

and its data component's entry. The system automatically 
prevents users from accessing page spaces and their data 

components. 


Abbreviation: UPDPW 
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DEFINE PAGESPACE 
DEFINE PAGESPACE EXAMPLES 





Define a NOSWAP Page Space: Example 1 


//DEFPGSP1 JOB see 
S/STEPI EXEC PGM=IDCAMS 


//VOLUME DD VOL=SER=VSERO05, UNIT=DISK, DISP=OLD 
//SYSPRINT DD SYSOUT=A 
“/SYSIN DD * 


DEFINE PAGESPACE - 
CNAMECSYS1.PAGE2) - 
CYLINDERS(10) - 
VOLUMESCVSERO5) —- 
CONTROLPWCPASSWD1) - 
UPDATEPWCPASSWD2) - 
READPWCPASSWD3)) 

1% 


Job control language statement: 


¢ VOLUME DD, which describes the volume on which the data 
space is to be defined. , 


Because no catalog is explicitly specified with a CATALOG 
parameter or with JOBCAT or STEPCAT DD statements, VSAM assumes 
that the data space and page space are to be defined in the 
master catalog. 


The DEFINE PAGESPACE command defines a page space. This page 
space will have the UNIQUE attribute and hence a new data space 
will be created for its exclusive use. Its parameters are: 


e NAME, which specifies the name of the page space, 
SYS1.PAGEZ2. 


> ® CYLINDERS, which specifies that the page space is to occupy 
3 10 cylinders. The page spaces are never extended. 


@ YOLUMES, which specifies that the page space is to reside on 
volume VSERO5. 


@ CONTROLPW, which specifies the control password for the page 
space is PASSWD1. 


e UPDATEPWN, which specifies the update password for the page 
space is PASSWD2. 


e READPW, which specifies the read password for the page space 
is PASSWD3. 


The page space defaults to UNIQUE and NOSWAP. 
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Define a SWAP Page Space 
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DEFINE PAGESPACE 
in a Catalog: Example 2 


DEFPGSP2 JOB... 

STEP1 EXEC PGM=IDCAMS 
SYSPRINT DD SYSOQUT=A 
SYSIN DD * 

DEFINE PAGESPACE - 
CNAMECSYS1.PAGE1) - 
CYLINDERS(10) - 
VOLUMESCVSERO5) - 
SWAP - 
CONTROLPWCPASSWDI) - 
UPDATEPNCPASSWD2) - 
READPWCPASSWD3)) 


use no catalog is explicitly specified with a CATALOG 

meter or with JOBCAT or STEPCAT DD statements, VSAM assumes 
the data space and page space are to be defined in the 

er catalog. 


DEFINE PAGESPACE command defines a page space. Its 
meters are: 


NAME, which specifies the name for the page space: 
SYS1.PAGE1. Because the page space is unique, the page 
space's name is put into the DSCB Cin the volume's VTOC) 
that describes the space allocated to the page space. 


CYLINDERS, which specifies that the page space occupies 10 
cylinders and cannot be extended. 


VOLUMES, which identifies the volume on which the page space 
is to reside. Because no DD statement describes the volume, 
an attempt is made to dynamically allocate the volume. 
Volume aaa must be mounted as permanently resident or 
reserved. | 


SWAP, which specifies the page space will be used to store 
local system queue area (LSQA) pages. , 


CONTROLPW, which specifies the control password for the page 
space is PASSWD1. 


UPDATEPW, which specifies the update password for the page 
space is PASSND2. | 


READPW, which specifies the read password for the page space 
1s PASSWD3. 


page space defaults to UNIQUE. 
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DEFINE PATH 


DEFINE PATH 


The DEFINE PATH command defines a path directly over a base 
cluster or over an alternate index and its related base cluster. 
The format of this.command is: 








DEFINE PATH 
| ( NAME ( ) 

PATHENTRY(entrynamel/password] ) 

[CATTEMPTS (number! 2)] 

[AUTHORIZATION entrvpoint£ string])] 

[CODE(code)] 

[CONTROLPW( password) ] 

[FILE( ddname)] 

[MASTERPW( password) ] 

[MODEL Centrynamel /password] 


[ catnamel/password]])]1 
C[OWNER(Cownerid)] 

[READPW password)] 
[TO(date} |] FOR(days)] 
[UPDATE | NOUPDATE] 
[UPDATEPW( password)1) 


[CATALOG(catnamel /password])] 
DEFINE can be abbreviated: DEF 


DEFINE PATH PARAMETERS 


Required Parameters 


PATH 
specifies that a path is to be defined. 


NAME Centryname]) 


specifies the path's name. 


PATHENTRY (Centrynamel/password]) 
when the path consists of an alternate index and its base 
clusters, entryname identifies the alternate index entry. 
Wnen the path is opened to process data records, both the 
alternate index and the base cluster are opened. 


When the path consists of a cluster without an alternate 
index, entryname identifies the cluster. You can define 
the path as though it were an alias for the cluster. This 
allows you to specify no-update access to the cluster, so 
that the upgrade set will not be required or updated when 
the cluster is opened (provided the cpen does not cause 
sharing of a control block structure specifying UPDATE). 
You can also establish protection attributes for the 
alternate name, separate from the protection attributes of 
the cluster. 


If the cluster or alternate index entry is 
password-protected, you must supply the entry's master 
password. When you identify the catalog with the 
CATALOG parameter, you can supply the catalog's master 
password instead of the entry's password. RACF: The 
alter RACF authority to the cluster, alternate index 
entry or catalog is required. 


Abbreviation: PENT 
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Optional Parameters 





DEFINE PATH 


ATTEMPTS (number |2) 


specifies the maximum number of times the operator can try 
to enter a correct password in response to a prompting 
message. 


This parameter only has effect when the path's master 
Password is not null. A prompting message is issued only 
when the user has not already supplied the appropriate 
password. 


is an integer from 0 to 7 and can be expressed in 
ote (nd, hexadecimal (X'n'), or binary CB*n') 
orm. 


Note to TSO users: At a TSO terminal, the logon password 
is checked first, before the user is prompted to supply a 
password for the path. Checking the logon password counts 
as one attempt to obtain a password. If ATTEMPTS is not 
specified, the user has one attempt to supply the path's 
password, because the default is 2. 


Abbreviation: ATT 


AUTHORIZATION(entrypoint£ string]) 


specifies that a user-~security-verification routine CUSVR) 
is available for additional security verification. When a 
protected path is accessed and the user supplies a correct 
password other than the cluster's master password, the USVR 
receives control. For details on the USVR, see Catalog 
Administration Guide. 


If a USVR is loaded from an unauthorized library during 
access method services processing, an abnormal termination 
will occur.— See "Authorized Program Facility™ in 


This parameter only has effect when the path's master 
password is not null. 


specifies the name of the USVR. 
specifies information to be passed on to the USVR when 


it receives control to verify authorization. 


Abbreviation: AUTH 


CATALOG( catnamel/password]) 


identifies the catalog that contains the entry of the 
cluster or alternate index named in the PATHENTRY 
parameter. For information about the order in which a 
catalog is selected if the catalog's name is not specified, 
see "Order of Catalog Selection for DEFINE™ on page 16. 


If the cluster's or alternate index's entry is 
password-protected and its catalog is also 
password-protected, you must specify the master password 
for either the entry or the catalog. 


specifies the catalog's name. 


specifies the catalog's master password. RACF: The 
alter RACF authority to the catalog is required. 


If the catalog's volume is physically mounted, it is 


dynamically allocated. The volume must be mounted as 
permanently resident or reserved. 
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DEFINE PATH 
Abbreviation: CAT 
CODE (code) 


specifies a code name for the path. 


If an attempt is made to access a password-protected path 
without first supplying an appropriate password, a 
prompting message is issued to the operator's console. The 
prompting message includes the code name, which identifies 
the path without revealing its entryname. 


This parameter only has effect when the path's master 
password is not null. When code is not specified, the 
prompting message identifies the path with its entryname. 


CONTROLPW( password) 
specifies a control password for the path. Control 
interval processing is not permitted through a path; the 
control password will permit read and write operations 
against the base cluster. 


If a read or update password is the only password specified 
for the object, it (the highest-level password) propagates 
ve and becomes the password for all higher unspecified 
evels. 


Abbreviation: CTLPW 
FILE(ddname) 


specifies the name of a DD statement that identifies the 
recovery volume of the alternate index or cluster named 
with the PATHENTRY parameter. FILE is only used when the 
path 1s defined in a recoverable catalog. 


The recovery volume is the first volume of the base 
cluster's index component when PATHENTRY names a 
key-sequenced cluster or an alternate index over a 
key~sequenced cluster. 


The recovery volume is the first volume of the base 
cluster's data component when PATHENTRY names an 
entry~sequenced cluster or an alternate index over an 
entry-sequenced cluster. 


When FILE is not specified, an attempt is made to 
dynamically allocate the cluster's recovery volume. The 
volume must be mounted as permanently resident or reserved. 


MASTERPW( password) 
specifies a master password for the path. The master 
password allows all operations against the path 


If the master password is not specified, the path's 
highest-level password propagates upward and becomes the 
password for all higher levels, including the master 
password. 


If all passwords are null, ATTEMPTS, AUTHORIZATION, and 
CODE have no effect until the master password is specified. 


Abbreviation: MRPW 


MODEL (entrynamel /password] 
[ catnamel /password]]) 
identifies an existing path entry that is to be used as a 
model for the path being defined. 


You can use some attributes of the model and override 
others by explicitly specifying them in the definition of 
the path. When you do not want to add or change any 
attributes, you specify only the entry type CPATH), the 
path's name, its alternate index's or cluster's name, and 
the model entry's name. 
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DEFINE PATH 


he names the entry to be used as a model. entryname must 
( ; name a path entry. 


specifies a password. If the model entry is 
password-protected and it 1s cataloged in a 
password-protected catalog, you must supply the read 
Cor higher level) password of either the model entry 
or its catalog. If you specify both passwords, the 
catalog's password is used. RACF: The read or higher 
RACF authority to the model or catalog is required. 


If you are not specifying new protection attributes 
for the path (that is, the model's passwords and 
protection attributes are being copied), you must 
supply the master password of either the model entry 
or its catalog. RACF: The alter RACF authority to the 
model or catalog is required. 


names the model entry's catalog. You must identify 
the catalog that contains the model entry for either 
of these cases: 


@ If you specify the catalog's password instead of 
the model entry's password. 


e If the model entry's catalog is not identified 
with a JOBCAT or STEPCAT DD statement, and is not 
the master catalog. 


If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. For information 
about the order in which a catalog is selected when 


aa the catalog's name is not specified, see "Order of 
| Catalog Selection for DEFINE" on page 16. 
OWNER( ownerid) 


specifies the identification of the path's owner. 


Note to TSO users: If the owner is not identified with the 
OWNER parameter, the TSO user's userid becomes the ownerid. 


READPW( password) 
specifies a read password for the path. The read password 
conte read operations against the base cluster's data 
records. 


Abbreviation: RDPW 
TO( date) | FOR({( days) 


specifies the retention period for the path. The path is 
not automatically deleted when the expiration date is 
reached. When a retention period is not specified, the 
path can be deleted at any time. 


TOl( date) 
specifies the date, in the form yyddd, where yy is the 
year and ddd is the Julian date (001, for January 1, 
through 365, for December 31), through which the path 
is to be Kept before it is allowed to be deleted. 


FOR(davs) 
specifies the number of days for which the entry is to 
be kept before it is allowed to be deleted. days can 
be expressed in decimal (n), hexadecimal (X'n'), or 
binary CB'n') form. 


f The maximum number that can be specified for days is 
x 


9999. If the number specified is 0 through 1830, the 
retention period is the number of days specified. If 
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DEFINE PATH 


the number specified is between 1831 and 9999; the | 
| retention period is through the year 1999. 


UPDATE | NOUPDATE | | 
specifies whether the base cluster's upgrade set is to be © 
| 7 allocated when the path is opened for processing. 


The upgrade set is a group of alternate indexes associated 
‘ with the base cluster. The alternate indexes are opened 
whenever the base cluster is opened. 


UPDATE 
specifies that when records in the base cluster are 
modified or deleted, or when records are added to the 
base cluster, each alternate index in the base 
cluster's upgrade set is modified to reflect the 
| change in the cluster's data, just as a key~sequenced 
| cluster's index is modified each time the cluster's 
| data changes. 


Abbreviation: UPD 


NOUPDATE 
specifies that, when opening the path, the path's base 
cluster is to be allocated and the base cluster's 
upgrade set is not to be allocated. 


You can specify the NOUPDATE attribute for the path 
even though the UPGRADE attribute is set for one of 
the base cluster's alternate indexes. 


When a path points to a base cluster that has a large 
upgrade set (that is, many alternate indexes are 
associated with the base cluster), and the path is 
defined with the NOUPDATE attribute, you can open the 
path, and consequently the base cluster, and none of 
the alternate indexes will be opened. 


Note: NOUPDATE will be overridden by opening the 
path, allowing sharing of a control block structure 
that permits UPDATE. 


Abbreviation: NUPD 


UPDATEPW( password) 
specifies the update password for the path. The update 
password permits read and write operations against the base 
cluster's data records. 


If a read password is the only password specified for the 
object Cthat is, it is the highest-level password), it 
propagates upward and becomes the password for all higher 
levels. If you specify a higher-level password and do not 
specify an update password, the update password is null. 


Abbreviation: UPDPW 
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DEFINE PATH 
DEFINE PATH EXAMPLE 


( Define a Path: Example 1 


In this example, a path is defined. Previous examples 
illustrate the definition of the path's alternate index, 
EXAMPLE.AIX, and the alternate index's base cluster, 
EXAMPLE.KSDS2. The alternate index, path, and base cluster are 
defined in the same catalog, USERRCAT. 


//DEFPATH JOB is 

S/STEPI EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD 3 

DEFINE PATH - 

CNAMECEXAMPLE.PATH) —- 
PATHENTRYCEXAMPLE.AIX/AIXMRPW) —- 
READPWNCPATHRDPW) ) - 


CATALOGCUSERRCAT/USERUPPW) 
7 


The DEFINE PATH command builds a path entry to define the path 
EXAMPLE.PATH. A copy of the path entry is placed in the catalog 
recovery area, because the path entry is being defined into a 
recoverable catalog. An attempt is made to dynamically allocate 
the catalog recovery area on volume VSERO]. The command's 
parameters are: 


e NAME, which specifies that the path's name is EXAMPLE.PATH. 


e PATHENTRY, which identifies the alternate index, 
EXAMPLE.AIX, that the path provides access to. 


( @ READPH, which specifies the path's read password, PATHRDPW. 


e CATALOG, which in this example supplies the catalog's update 
password, USERUPPNW. 
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DEFINE SPACE 


DEFINE SPACE 


The DEFINE SPACE command defines a VSAM data space in a VSAM 
catalog. The format of this command is: 





1 DEFINE SPACE 
(£CANDIDATE | 
CYLINDERS(primary£€ secondary])| 
RECORDS(primary[ secondary] ) 
RECORDSIZE(average maximum) | 


TRACKS(primary£ secondary1)} 
VOLUMES(volser[f yolser...1) 
[FILE(ddname)]) 


[CATALOG( catnamel /password1)] 





DEFINE can be abbreviated: DEF 


DEFINE SPACE PARAMETERS 


Required Parameters 


SPACE 
specifies that a data space is to be defined. You can also 
ra the DEFINE SPACE command to reserve a volume for VSAM's 
Future use. | 


Abbreviation: SPC 


CANDIDATE | 
CYLINDERS(primary£ secondary]}| 
RECORDS(primaryl£ secondary]) RECORDSIZElaverage maximum)! 
TRACKS(primaryi secondary!) 
specifies the volume(€s) to be reserved for VSAM's future 
use or specifies the amount of space to be allocated in 
terms of cylinders, number of records, or tracks. 


You must specify only one of the following parameters: 
CANDIDATE, CYLINDERS, TRACKS, or RECORDS. When ver Pld 
RECORDS, you must also specify RECORDSIZE. When y 

specify CYLINDERS or TRACKS, you cannot specify RECORDSIZE. 


CANDIDATE 
specifies that the volumes listed in the VOLUMES 
Parameter are reserved for future use by VSAM. An 
ownership indicator is set ina format-@ DSCB in the 
volume's table of contents (VTOC). The volumes are 
reserved for use by the catalog, but no space is 
allocated Cother than the primary CRA allocation if 
the catalog is recoverable). Each volume so reserved 
is called a candidate volume. If CANDIDATE is not 
specified, you must specify one of the following 
parameters: CYLINDERS, TRACKS, or RECORDS. 


If a VSAM data space already exists on the volume, you 
cannot specify CANDIDATE. CYou can, however, use the 
ALTER command to identify the volume as a candidate 
volume for a VSAM object other than the volume's 
catalog.) 


Abbreviation: CAN 


iy, | 
So 
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DEFINE SPACE 


CYLINDERS(primaryl secondary])| 
RECORDS(primaryl secondary]) 
RECORDSIZE{average maximum) | 
TRACKS(primary[ secondary]) 
specifies the amount of space to be allocated in terms 
of tracks, cylinders, or number of records. 


If RECORDS is specified, the space required is 
calculated in terms of the number of records, but the 
space is allocated by tracks. However, if you specify 
TRACKS or RECORDS and the minimum number of tracks 
exceeds a cylinder, space is allocated in terms of 
cylinders. 


Primary 
specifies the initial amount of space (primary 
extent) to be allocated to the data space. 
primary can be expressed in decimal (Cn), 
hexadecimal (X'n"}, or binary (CBin') form. 


secondary 
specifies the amount of space that is to be 
allocated to the data space each time it is 
extended. Once the primary extent is filled, the 
data space can expand to include a maximum of 15 
secondary extents if you have specified a 
secondary extent amount. secondary can be 
expressed in decimal (n), hexadecimal (X'n'), or 
binary (CB'n'") form. 


The secondary space allocation is rounded upward 
to the nearest whole cylinder regardless of your 

specification in terms of TRACKS or RECORDS. 
Consequently, the total amount of space allocated 
re Ng data space might exceed the predicted 
imit. 


When the data space is the first data space ona 
volume that belongs to a recoverable catalog, the 
primary amount is increased by one cylinder. 


Abbreviations: CYL, REC, and TRK 


RECORDSIZElaverage maximum) 
specifies the average and maximum lengths, in bytes, 
of the records. 


average and maximum can be any integer value between 1 
and 32 761, expressed in decimal (n), hexadecimal 
CX'n'), or binary (CB'n') form. When you specify the 
RECORDS parameter, you must also specify RECORDSIZE; 
otherwise, you cannot specify RECORDSIZE. 


Abbreviation: RECSZ 


VOLUMES(volser[ volser...]) 


specifies the volumes on which data spaces are to be 
defined or volumes to be reserved as candidate volumes for 
VSAM's future use. If two or more volumes are specified 
and an amount of space is specified (that is, TRACKS, 
CYLINDERS, or RECORDS and RECORDSIZE is specified) the 
amount specified for the primary allocation is allocated on 
each volume. The specified volumes must all be of the same 
device type. When the volume already has a data space on 
it, subsequent data spaces can be defined and must be 
cataloged in the catalog that owns the volume. A data 
space can be defined on a mass storage volume. 


Abbreviation: VOL 
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DEFINE SPACE 


Optional Parameters 
CATALOG( catnamel /password1]) 


identifies the catalog in which the data space is to be 
defined. The CATALOG parameter supplies the name and 
password, when required, of the catalog that contains the 
volume entry that describes the verume on which the data 
space is to be allocated. 


If the DEFINE SPACE command is used to allocate the 
volume's first VSAM data space or to identify the volume as 
a candidate volume, the CATALOG parameter identifies the 
catalog that is to contain the volume's catalog entry and 
is to own the volume. (CFor more information about VSAM 
volume ownership, see ini j ide.) 


If the catalog's volume is physically mounted, it is 
dynamically allocated. For information about the order in 
which catalogs are selected, see "Order of Catalog 
Selection for DEFINE™ on page 16. 


specifies the name of the catalog. 


W 
specifies a password. If the catalog is password 
protected, you must supply the update- or higher-level 
password. RACF: The update or higher RACF authority 
to the catalog is required. 


Abbreviation: CAT 
FILE(ddname) 


specifies the name of the DD statement that identifies the 
device type and volumes to be used for space allocation. 
You cannot use concatenated DD statements to describe more 
than one volume. 


If FILE is not specified and the volume is physically 
mounted, the volume(s) identified with the VOLUMES 
parameter is dynamically allocated. Each dynamically 

abe socio volume must be mounted as permanently resident or 
reserved. 
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DEFINE SPACE 


DEFINE SPACE EXAMPLE 


Define a Data Space: Example 1 


In this example, a data space is defined. The data space is to 
be used to allocate space for VSAM clusters that are 
subsequently defined. 


//DEFSPC1 JOB 


//JOBCAT DD DSN=D27UCAT1,DISP=SHR 
S/STEPI EXEC PGM=IDCAMS 

“/7SYSPRINT DD SYSOUT=A 

S/SYSIN DD x 


DEFINE SPACE - 
CCYLINDERSC30 10) - 
VOLUMESCVSERO5)) - 
CATALOG(D27UCATI1/USERMRPW) 
7% 


Access method services defines the data space and allocates its 
Space on volume VSERO5. The data space is cataloged in 
D27UCAT1, because a JOBCAT DD statement is specified. All 
future data spaces and clusters on volume VSERO5 must also be 
cataloged in the same catalog. Non-VSAM data sets on the volume 
reside in areas that are not allocated to a VSAM data space. 


The DEFINE SPACE command defines a VSAM data space. Its 
parameters are: 


6 CYLINDERS, which specifies that 30 cylinders are to be 
allocated for the data space. When the data space is 
extended, it is to be extended in increments of 10 
cylinders. 


e VOLUMES, which specifies the volume serial number of the 
volume on which the data space is to be defined: VSEROS5. 


_@ © CATALOG, which in this example supplies the user catalog's 


name, D27UCAT1, and its master password, USERMRPHW. 
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The DEFINE USERCATALOG|IMASTERCATALOG command defines a VSAM user S 
or master catalog. When you use this command, you can specify = 
attributes for the catalog as a whole and for the components of 

the catalog. 


The format of this command is: 


DEFINE USERCATALOG | MASTERCATALOG 

(NAME Centryname) 
{CYLINDERS(primaryl . 

RECORDS (primarvl 

TRACKS (primarvl 
VOLUME(volser) 
[LATTEMPTS(number[12)1] 
[LAUTHORIZATIONCentrvpoint£ string])]1 
EBUFFERSPACE(size!3072)1 
[CODE(code)] 
[CONTROLPW( password) 1 
CDESTAGEWATT | NODESTAGEMAIT | 
[FILE€(ddnameJ] 
[MASTERPW( password) ] 
C[MODELCentrynamel/password1]f catnamel/password]1)1 
[OWNER ownerid)] | 
[READPWCpassword)] 
[ RECOVERABLE | NOTRECOVERABLE] 
[TO( date) | FOR(days)] 
[UPDATEPW( password)] 
[WRITECHECK | NOWRITECHECK] ) 


ATA 
(C{BUFFERSPACE(size)] 
[CYLINDERS(primary[ secondary])| 
RECORDS(primaryE secondary])| | 
TRACKS(primaryl secondaryJ)1] — 
[DESTAGEWAIT | NODESTAGEWAIT 1 tet 
[RECORDSIZEl(average maximum 
[RECOVERABLE | NOTRECOVERABLE] 
C[(WRITECHECK | NOWRITECHECK] ) 1 


[INDEX 
(LCYLINDERS (primary) | 
RECORDS (primary) | 
TRACKS (primary )] 
[DESTAGEWAIT | NODESTAGEWAITI 
[WRITECHECK | NOWRITECHECK] J] 


CCATALOG(mastercatnamel/password])] 





DEFINE can be abbreviated: DEF 


DEFINE USERCATALOG|MASTERCATALOG PARAMETERS 


Required Parameters 


USERCATALOG | MASTERCATALOG 
specifies that a catalog is to be defined. 


USERCATALOG 
specifies that a user catalog is to be defined. 
USERCATALOG is followed by the parameters specified 
for the catalog as a whole. RACF: The update or 
higher RACF authority to the master catalog is ae 
required. fo. 


Abbreviation: UCAT : ° 
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ee MASTERCATALOG 
aoe Processing is identical for the MASTERCATALOG and 
3 USERCATALOG parameters. When you specify 


MASTERCATALOG, a user catalog is created. You can, 
however, establish a user catalog as a master catalog 
at IPL time. _For a description of this procedure, see 
C : 


Abbreviation: MCAT 
NAME Centryname) 


Specifies the name of the catalog being defined. 


CYLINDERS(primaryvlI secondary))| 
RECORDS(primaryl[ secondary])| 

TRACKS(primarvE[ secondary!) 
specifies the amount of space to be allocated in terms of 
cylinders, tracks, or number of records. You can specify 
the amount of space as a parameter of USERCATALOG, as a 
parameter of USERCATALOG and DATA, or as a parameter of 
USERCATALOG, DATA, and INDEX. 


If you specify less than one cylinder of space for a 
recoverable catalog, your DEFINE command will fail. 


For a description of the difference in space allocation 
depending on which parameters you specify, see Catalog 

tr on Gul . This guide also provides information 
about estimating the amount of space to be specified for a 
catalog. 


Primary[€ secondary] 
specify the size of the primary and secondary extents 
to be allocated. Once the primary extent is filled, 
__ the space can expand to include a maximum of 13 
| additional secondary extents if you have specified a 
| secondary allocation amount 


primary and secondary can be expressed in decimal (n), 
hexadecimal (X'n"), or binary (B'n') form. Secondary 
allocation should be specified in case the catalog has 
to be extended. 


Abbreviations: CYL, REC, and TRK 


VOLUME (volser) 
specifies the volume that is to contain the catalog. The 
volume cannot be currently owned by any other VSAM catalog. 


The VOLUME parameter interacts with other DEFINE CATALOG 
parameters. You should ensure that the volume you specify 
for the catalog is consistent with the catalog's other 
attributes: 


e CYLINDERS, RECORDS, TRACKS: The volume contains enough 
unallocated space to satisfy the catalog'sS primary 


space requirement. (Space on the volume might already 
be econo to non-VSAM data sets and system data 
sets. 


e FILE: The volume information supplied with the DD 
statement is consistent with the information specified 
for the catalog and its components. 

A user catalog can be defined on a mass storage volume. 


Abbreviation: VOL 
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DEFINE USERCATALOG | MASTERCATALOG 
Optional Parameters 


| _ , 
ATTEMPTS (number! 2) + F 
specifies the maximum number of times the operator can try Senne 
to enter a correct password in response to a prompting 
message. 
number 


is an integer from 0 to 7 and can be expressed in 
decimal (n), hexadecimal (X'n'), or binary (B*n'*) 
form. If 0 is specified, the operator is not prompted 
and af not allowed to enter a password from the 
console. 


Note to TSO users: At a TSO terminal the logon password is 
checked first, before the user is prompted to supply a 
password for the catalog. Checking the logon password 
counts as one attempt to obtain a password. If ATTEMPTS is 
not specified, the user has one attempt to supply the 
catalog's password, because the default is 2 


Abbreviation: ATT 
AUTHORIZATION(Centrypointl string]) 


specifies that a user-security-verification routine CUSVR) 
is available for additional security verification. When a 
protected catalog is accessed and the user supplies a 
correct password other than the catalog's master password, 
the USVR receives control. For information on the 
user-security-verification routine, see 


entrypoint 
specifies the name of the USVR. 


specifies information to be passed on to the USVR when 
it receives control to verify authorization. 


Abbreviation: AUTH 


BUFFERSPACE (size! 3072) 
specifies the minimum space, in bytes, to be provided for 
buffers when using the catalog Cone not residing on a 


3380). Decimal values you can specify are 3072, 4096, 
5120, 61494, 7168, and 8192. 


Size | 
is the amount of space, in bytes, to be provided for 
buffers. Size can be expressed in decimal (Cn), 
hexadecimal (X'n'), or binary CB'n') form, but must 
not exceed 16776704. 


Abbreviation: BUFSP 
CATALOG(mastercatnamel /password] ) 


specifies the name and password of the master catalog. If 
the master catalog is password protected, its update- or 
higher- level password must be provided in this parameter or 
in response to prompting. 


is the name of the master catalog that is required 
when a user catalog is being defined. 


specifies the update- or higher-level password of the 
master catalog that is required when a user catalog is 
being defined, if the master catalog is password 
protected. 


Abbreviation: CAT 
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CODE( code) 
a specifies a code name for the catalog being defined. If an 
( attempt is made to access a password-protected catalog 


without a password, the code name is used in a prompting 
message; the code enables the operator to be prompted for 
the password without disclosing the name of the catalog. 
If CODE is not specified, the operator will be prompted 
with the name of the catalog. 


CONTROLPW( password) 
specifies a control password for the catalog being defined. 
The control password permits the same operations as the 
update password. 


If a read or update password is the only password specified 
for the catalog, it (the highest-level password) propagates 
upward and becomes the password for all higher levels. 

When the master password is specified but the control 
password is not specified, the control password is null. 


Abbreviation: CTLPW 
DESTAGEWAIT | NODESTAGEWAIT 


specifies whether a user catalog that is stored on a mass 
storage volume is to be destaged synchronously or 
asynchronously with respect to the program that closes it. 


If the user catalog is not stored on a mass storage volume, 
the attribute is ineffective until the direct access 
storage volume, the catalog is stored on is converted to a 
mass storage volume Cusing the CONVERTV command described 
in OS“VS Mass Storage System (MSS) Services: Reference 


Information). 


If one of these parameters is specified for the data 
ner component of a catalog and the other parameter is specified 
( | for the index component, the parameter specified for the 
index component applies to both components, because the 
rea ral set of the index of a catalog is embedded in the 
ata. 


DESTAGEWAIT 
indicates that destaging is to be completed before 
control is returned from VSAM to the program that 
issues the CLOSE macro. VSAM can thus notify the 
program whether destaging was successful. 


Abbreviation: DSTGW 


NODESTAGEWAIT ; 
indicates that notification of unsuccessful destaging 
1s to be made only by a message to the operator. 


Abbreviation: NDSTGW 
FILE(ddname) 


specifies the name of the DD statement that identifies the 
device and volume to be used for the catalog. The DD 
statement should specify DISP=OLD to prevent premature 
space allocation on the volume. 


If FILE is not specified and the catalog's volume is 
physically mounted, the volume identified with the VOLUME 
parameter is dynamically allocated. The volume must be 
mounted as permanently resident or reserved. 


MASTERPW( password) 
specifies a master password for the catalog being defined. 
A catalog must have a master password in order for VSAM 
data sets cataloged in it to be password-protected. The 
AUTHORIZATION, CODE, and ATTEMPTS parameters have no effect 
unless the catalog has a master password associated with 
it. The master password allows all operations; it is 
required to open the catalog as a data set. 
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If a master password is not specified for the catalog, the 


catalog's highest-level password propagates upward and A 
becomes the password for all higher levels, including the “ 
master password. The master password is null when no other ol 


passwords are specified. 
| Abbreviation: MRPW 
MODELlentrynamel/password1[ catnamel/passwordi]) 


specifies that an existing master or user catalog is to be 
used as a model for the user catalog being defined. 


It is possible to use an already defined master or user 
catalog as a model for another user catalog. 


When one entry is used as a model for another, its 
attributes are copied as the new entry is defined. You may 
use some attributes of the model and override others by 
eae specifying them in the definition of the user 
catalog. 


If a model is used, you must specify certain parameters 
even though no attributes are to be changed or added. The 
name of the user catalog to be defined and volume and space 
information must always be specified as parameters of 
USERCATALOG. 


specifies the name of the master or user catalog to be 
used as a model. 


password 
specifies a password. If the catalog to be used as a 
model is password-protected, a password is required. 


If you specify both passwords (that is, the password fe 
following entryname and the password following | 
catname), the password following catname is used for 
authorization. 


If the protection attributes are to be copied, enter 
the master password of the catalog being used as a 
model. RACF: The alter RACF authority to the catalog 
is required. If passwords are not to be copied, any 
password except the master can be used. 


specifies the name of the catalog to be used as a 
model. This parameter is required if the model 
catalog is neither the master catalog nor a catalog 
identified by a JOBCAT or STEPCAT DD statement. 


OWNER ( ownerid) 
specifies the identification of the owner of the catalog 
being defined. 


READPW( password) 
specifies a read password for the catalog being defined. 
The read password permits the user to list the catalog's 
entries. (Passwords and protection attributes are listed 
only when the master-level password is supplied.) 


Abbreviation: RDPW 


RECOVERABLE | NO B 
specifies whether a catalog recovery space is to be created 
on each volume owned by the catalog. 


RECOVERABLE 
specifies that a catalog recovery space is to be an 
created. : 


On the catalog's volume, the catalog recovery space is 
allocated from the catalog's data space. On 
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subsequent volumes owned by the catalog, the catalog 
ee recovery space is allocated from the first data space 
( defined on the volume. 


Primary allocation for a CRA is one cylinder. Once a 
primary extent is filled, the CRA can expand to 
include a maximum of 15 additional extents. 
Allocation for each secondary extent is one cylinder. 


The number of records a CRA can contain varies with 
the device type (for example, for a 3339 with 20 
control intervals per track, each extent will 
accommodate approximately 370 records). 


Abbreviation: RVBL 


NOTRECOVERABLE 
specifies that no catalog recovery space is to be 
created. 


Abbreviation: NRVBL 
TO( date) | FOR( days) 


specifies the retention period for the catalog being 
defined. If no value is coded, the catalog can be deleted 
whenever it is empty. 


TO(date) 
specifies the date, in the form yyddd, where yy is the 
year and ddd is the number (001 through 365) of the 
day through which the catalog being defined is to be 


kept. 
FOR( days) 
specifies the number of days for which the catalog 
( being defined is to be Kept. 
. The maximum number that can be specified is 9999. If 


the number specified is 0 through 1830, the catalog is 
retained for the number of days specified; if the 
number is between 1831 and 9999, the catalog is 
retained through the year 1999. 


days 


can be expressed in decimal (n), hexadecimal 
CX'n'), or binary (CB*¥n') form. 


UPDATEPW( password) 


specifies an update password for the catalog being defined. 
The update password permits entries to be added to the 
catalog being defined. The catalog must be update 
password-protected in order to prevent unauthorized users 
from cataloging data sets. 


If a read password is the only password specified for the 
catalog (that is, it is the highest-level password), it 
propagates upward and becomes the password for all higher 
levels. If you specify a higher-level password and do not 
aa an update or read password, the update password is 
null. 


When you anticipate using the catalog to contain many 
non-VSAM entries, you should consider allowing the 
catalog's update password to be null (that is, to specify a 
master password but not an update password). A null update 
password allows you to alter and delete non-VSAM entries 
without having to supply the catalog's password. 


Abbreviation: UPDPW 


WRITECHECK | NOWRITECHECK 
specifies whether the catalog is to be checked by a direct 
access device operation called write check when a record is 
written to the device. 
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WRITECHECK _ oO 
specifies that a record is to be written and then 
read, without data transfer. 


Abbreviation: WCK 


NOWRITECHECK : : 
specifies that the catalog is not to be checked by a 
write check when a record is written to the device. 


Abbreviation: NWCK 


DATA AND INDEX COMPONENTS OF USERCATALOG 


Attributes can be specified separately for the catalog's data 
and index components. The DATA and INDEX parameters are listed 
at the beginning of this section. These parameters are 
described in detail as parameters of the catalog as a whole. 
Restrictions are noted with each parameter's description. 
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DEFINE USERCATALOG | MASTERCATALOG 
DEFINE USERCATALOG EXAMPLES 


Defining a VSAM User Catalog, Having Calculated Its Space Requirements: Example 1 


In this example, a user catalog is defined. The user catalog's 
data space is not available to contain other VSAM objects. The 
catalog is to be large enough to contain information about: 


° 100 key~sequenced clusters (that is, indexed VSAM data sets) 


e 10 entry-~sequenced clusters (that is, sequential nonindexed 
VSAM data sets) | 


e 5 key-sequenced clusters with Berernace indexes to be 
upgraded 


@ 5 entry-~sequenced clusters with alternate indexes to be 
upgraded 


e 10 alternate indexes 

e 10 paths 

e 200 aliases 

e 10 generation data sets 
e 1000 non-VSAM data sets. 


e 5 volumes (the number to be controlled by the catalog). 
Each volume is a 3330 volume and contains 20 data spaces. 


To determine how much space, in records and tracks, is required 
eee for the primary allocation of a catalog still to be defined in 
( your system, see Catalog Administration Guide. The number of 

records for the primary allocation of the catalog in this 

ep aie shown in the completed worksheet in Figure 3 on 

page 


When you define the catalog's space parameters, use the 
following format: 


DEFINE USERCATALOG - 
CTRACKS(Cprim secn) ... ) 


where: 


° prim = the minimum amount of space for the catalog data 
space's primary allocation. In this example, all the data 
space 1S assigned to the catalog itself. The calculated 
value of prim should be rounded upward to the next whole 
number of tracks that is an even multiple of the catalog 
allocation unit for the device type being used (For the size 
of an allocation unit, see 


Because the catalog resides on a 3330-1 volume, the value of 
prim is: 


prim = .09N + 3 = 152.4 = = 153 tracks 





Chapter 4. Functional Command Format 147 











Basic requirement = 10 records 

A_ = number of key-sequenced clusters 

A! = number of key-sequenced clusters with alternate 
indexes to be upgraded 

= number of entry-sequenced clusters 

number of entry-sequenced clusters with alternate 

indexes to be upgraded 

number of relative-record clusters 

number of alternate indexes 

number of path entries 

number of nonVSAM data set entries 

number of generation data group entries 

number of alias entries 

number of page spaces 

number of volumes, depending on device type, 

owned by the catalog: 

J! = number of 2305 volumes 

J? = number of 2314/2319 volumes 

J = number of 3330 and 3340/3344 volumes 

34 = number of 3330 Model 11 and 3350 volumes 

for each key-sequenced cluster and alternate index 

(KSDS) with space on more than two volumes, add 

“1° for each additional group otf one to tive 

volumes: 

= number of KSDSs with 3 to 7 volumes 

number ot KSDSs with 8 to 12 volumes 

number of KSDSs with 13 to 17 volumes 

tor each entry-sequenced cluster und relative-record 

cluster (ESDS) with space on more than five 

volumes, add “1"" for each additional group of one 

to eight volumes: 

L! = number of ESDSs with 6 to 13 volumes 

L2 = number of ESDSs with 14 to 21 volumes 

for each group of tour data spuces on u volume, 

add “1 

number of entry records required for the catalog’s 

data component (total of above) 


mH“ = ZTOAnNnMOA ww 
ow & 0 8 8 


NR 
W 


> ‘8 IASIS|SSS| of 3 





Figure 3. Completed Worksheet for Determining a Catalog's Space 
Requirements 


® secn = the minimum amount of space for each secondary extent 
of the catalog'’s data space. 


The number of tracks required for the catalog's primary 
extent is at least 153. This figure is an even multiple of 
an allocation unit for a 3330 device (3); therefore, no 
further rounding is. necessary. If VSAM extends the catalog, 
it should extend it in increments of 18 tracks. 


//DEFCAT2 JOB Bn 
“/STEPI EXEC PGM=IDCAMS 
/7SYSPRINT DD SYSOUT=A 
“7SYSIN DD ¥ 
DEFINE USERCATALOGC 
NAMECUSERCAT3) 
VOLUMECVSERO4) 
TRACKS(153 18) 


ee | 
i” 


Pe ~ 


eo 


es 
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The DEFINE USERCATALOG command defines a user catalog. Its 
parameters are: 


6 NAME, which specifies the name of the catalog, USERCAT3. 


e VOLUME, which specifies that the catalog is to reside on the 
volume whose serial number is VSEROG. 


e TRACKS, which specifies that the catalog's data space is to 
be 153 tracks. When the user catalog is extended, VSAM 
extends it in increments of 18 tracks. 


e Values and attributes that apply by default to the catalog 
are BUFFERSPACE = 3072 bytes, ATTEMPTS = 2, NOWRITECHECK, 
NODESTAGEWAIT, and NOTRECOVERABLE. 


Define a User Catalog Leaving Available Suballocatable Space: Example 2 


In this example, a user catalog is defined. The catalog will 
actually occupy only a portion of the space defined, leaving the 
remainder of the space available for the suballocation of other 
VSAM data sets. 


//DEFCATS JOB sais 

//STEPI EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

S/SYSIN DD x 

DEFINE USERCATALOG( - 

NAMECD27UCAT1) ~ 
MASTERPWCUSERMRPW) - 
UPDATEPWCUSERUPPW) - 
FORC365) - 
CYLINDERSC10 1)) - 
VOLUMECVSERO2) ) - 


AC 
CYLINDERSC3 1) - 
INDEXC - 
CYLINDERS(C1) ) - 
CATALOGCAMAST1I1/MASTUPNW]1 ) 
7% 


The DEFINE USERCATALOG command defines a user catalog, D2/7UCAT1. 
Its parameters are: 


6 NAME, which names the user catalog, D27UCAT1. 


® MASTERPW and UPDATEPW, which specify master and update 
passwords for the catalog: USERMRPW and USERUPPNW. 


e FOR, which specifies that the user catalog is to be retained 
for 365 days. 


e CYLINDERS, which specifies that 10 cylinders are to be 
allocated for the user catalog's data space. When the user 
catalog's data space is extended, it is to be extended in 
increments of 1 cylinder. 


e VOLUME, which specifies that the catalog is to reside on 
volume VSERO2. Volume VSERO2 will be dynamically allocated. 


@ DATA and INDEX, which specify that VSAM is to allocate 4 
cylinders for the catalog itself. VSAM determines the 
proportion of space that is allocated to the catalog's data 
and index components. The remainder of the catalog's data 
space (6 cylinders) is available to contain VSAM objects 
that reside in a nonunique data space. If the catalog's 
data component is extended, it is to be extended in 
increments of 1 cylinder. The catalog's index component is 
never extended. 


° CATALOG, which specifies that the user catalog connector 
entry is to be defined in the master catalog, AMAST1. 
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CATALOG provides the catalog's update password, MASTUPW1, so 
that the operator is not prompted to provide it. . 


Values and attributes that apply by default to the catalog 
are BUFFERSPACE = 3072 bytes, ATTEMPTS = 2, NOTRECOVERABLE, 
NOWRITECHECK, and NODESTAGENAIT. 


Define a User Catalog Using the MODEL Parameter: Example 3 


In this example, the user catalog defined previously, D27UCATI, 
is used as a model for the user catalog being defined, D27UCAT2. 


//DEFCATG JOB ie 
//STEPI EXEC PGM=IDCAMS 
“/STEPCAT DD DSNAME=D27UCAT1,DISP=SHR 
//SYSPRINT DD SYSOUT=A 
S/3SYSIN DD ¥ 
DEFINE USERCATALOGC( — . 
NAMECD27UCAT2) - 
MASTERPNCUSERMRPW) - 
UPDATEPNCUSERUPPW) - 
CYLINDERS(15 5) - 
VOLUMECVSERO3) - 
MODEL CD27UCATI/MRPWD27 - 
D27UCATI/MRPWND27) ) - 
CATALOGCAMASTI/MASTUPNWI) 


7% 


Job control language statement: 


STEPCAT DD, which makes a catalog available for this job 
step: D27UCAT1. 


The DEFINE USERCATALOG command defines catalog D27UCAT2. Its 
parameters are: 


NAME, which names the catalog, D27UCAT2. 


MASTERPW and UPDATEPW, which specify master and update 
passwords for the catalog: USERMRPW and USERUPPNH. 


CYLINDERS, which specifies that 15 cylinders are to be 
allocated for the catalog's data space. The catalog itself 
will reside within this data space. When the catalog's data 
space is extended, it is to be extended in increments of 5 
cylinders. 


VOLUME, which specifies that the catalog is to reside on 
volume VSERO3. Volume VSERO3 will be dynamically allocated. 


MODEL, which identifies D27UCAT1 as the catalog to use as a 
model for D27UCAT2. The attributes and specifications of 
D27UCAT1 that are not otherwise specified with the above 
parameters are used to define the attributes and 
specifications of D2Z7UCAT2. The master catalog, AMASTI, 
contains a user catalog connector entry which points to 
D27UCAT1L. This is why D27UCAT1 is specified as MODEL's 
catname subparameter. Values and attributes that apply to 
D27UCAT2 as a result of using D27UCAT1 as a model are FOR = 
365 days, CYLINDERS = 3 Cprimary) and 1 (secondary) for the 
data component and 1 Cprimary) for the index component, 
BUFFERSPACE = 3072 bytes, ATTEMPTS = 2, NOWRITECHECK, and 
NODESTAGEWAIT. 


CATALOG, which specifies that the user catalog connector is 
to be defined in the AMASTI1 catalog. The update password of 
AMAST1 is MASTUPWI1. 
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Define a VSAM Recoverable User Catalog: Example 4 
( | In this example, a recoverable user catalog is defined. 


//DEFCATS JOB goes 
//STEPI EXEC PGM=IDCAMS 


//NOL1 DD VOL=SER=VSERO1,UNIT=DISK, DISP=OLD 
7/SYSPRINT DD SYSOUT=A 
S/SYSIN DD % 


DEFINE USERCATALOGC - 
NAMECUSERRCAT) - 
MASTERPWCUSERMRPHD) - 
UPDATEPWCUSERUPPW) - 
TO0699365) - 
ATTEMPTS(C3) -~- 
CODECBEQUIET) - 
RECOVERABLE - 
TRACKS(@100) - 
FILECVOL1). - 
VOLUMECVSERO1) d= 

DATAC - 
RECORDS(C500 100)) - 
CATALOGCAMASTI/MASTUPWI) 
7% 


Job control language statement: 


e VOL1 DD, which describes the volume on which the catalog is 
to be defined. 


The DEFINE USERCATALOG command defines a user catalog, USERRCAT. 
Its parameters are: 


e NAME, which names the user catalog, USERRCAT. 


ac @ MASTERPW and UPDATEPW, which specify master and update 
( passwords for the catalog: USERMRPW and USERUPPNH. 


° TO, which specifies that the user catalog is to be retained 
until 31 December 1999. 


e ATTEMPTS, which specifies that the operator may be prompted 
for the correct password up to three times. 


e CODE, which specifies that the catalog is identified, in the 
prompting message to the operator, with the name "BEQUIET"®. 


8 RECOVERABLE, which specifies that the catalog's volumes 
contain catalog recovery areas and the LISTCRA, EXPORTRA, 
IMPORTRA, and RESETCAT commands can be used to restore 
entries in the catalog. 


® TRACKS, which specifies that 100 tracks are to be allocated 
for the user catalog's data space. No secondary allocation 
is specified. If additional VSAM space is required on the 
cabeltg it can be explicitly defined using the DEFINE SPACE 
comman 


e FILE, which points to the VOL1 DD statement. The VOLI1 DD 
statement directs the operating system scheduler to mount 
and allocate the volume on which the user catalog is to 
reside. In this example, the volume is not dynamically 
allocated. 


6 VOLUME, which specifies that the user catalog is to reside 
on volume VSEROI]. 





Chapter 4. Functional Command Format 151 








DEFINE USERCATALOG|MASTERCATALOG 


e 


DATA, which specifies that VSAM is to allocate space to 
accommodate 500 records for the user catalog. VSAM 
determines the total amount of space that is allocated to 
the catalog's data and index components. The remainder of 
the catalog's data space is available to contain the catalog 
recoverable area (CRA) and other VSAM objects that reside in 
a nonunique data space. If the catalog's data component is 
pects pal it is extended in increments to accommodate 100 
records. 


You may wish to estimate the amount of space which VSAM will 
actually allocate to the catalog in order to: 


- Ensure that the total amount of space specified via 
TRACKS is large enough. 


- Determine how much suballocatable space will be 
available. 


Because the catalog resides on a 3330-1, the total amount of 
space will be: 


aN + b = (0.1116 x 500) + 4 = 59.8 = 60 tracks 


CATALOG, which specifies that the user catalog connector is 
to be defined in the AMAST1 catalog. The update password of 
AMAST1 iss MASTUPW1. 


Values and attributes that apply by default to the catalog 
are BUFFERSPACE = 3072 bytes, NOWRITECHECK, and 
NODESTAGENWAIT. 
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! DELETE 


a The DELETE command deletes catalogs, VSAM data sets, and 
= non-VSAM data sets. The format of this command is: 


DELETE as entrynamel/password] ...1) 


ALTERNATEINDEX|! 
CLUSTER] 
GENERATIONDATAGROUP | 
NONVSAM | | 
PAGESPACE | 
PATH] 

SPACE | 
USERCATALOG 

[ERASE | NOERASE] 

[FILE(ddname)] 

[FORCE | NOFORCE] 

C PURGE | NOPURGE] 

[ SCRATCH | NOSCRATCH] 


[CATALOG( catnamel /password1)1 





DELETE can be abbreviated: DEL 


DELETE PARAMETERS 


Required Parameters 
Centrynamel/password]I entrynamel/password]... ]) 


ase: names the entries to be deleted. If more than one entry is 
to be deleted, the list of entrynames must be enclosed in 
parentheses. 7 


This parameter must be the first parameter following 
DELETE. 


is the name of the entry to be deleted or the volume 
serial number of the volume that contains a data space 
to be deleted. A generic name may be coded in order 
to delete multiple entries with one entryname. (For 
example, GENERIC.*®.BAKER is a generic name where "x" 
is any 1l- to 8-character simple name. ) 


If you are deleting a member of a non-VSAM partitioned 
data set, the entryname must be specified in the 
format: pdsnameCmembername). If you are deleting a 
non-VSAM data set that was defined by coding | 
DEVICETYPES(C0000) and VOLUMESC "*¥*xXxx'), then DELETE 
only uncatalogs the data set. It does not scratch it 
from the SYSRES volume. 


password 
specifies a password for a password-protected entry. 
Passwords may be specified for each entryname, or the 
catalog's password may be specified through the 
CATALOG parameter for the catalog that contains the 
entries to be deleted. Only certain types of catalog 
entries can be password protected, as specified below. 


To delete: 


° Alias, specify the catalog's update- or 
— higher-level password. RACF: The RACF alter 
: authority to the entry to which the alias is 
related is required. 
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| | e Alternate index, specify the entry's master 

| password, or the catalog's master password. RACF: 

| The RACF alter authority to the alternate index or 
to the catalog is required. 


e Cluster, specify the entry's master password, or 
the catalog's master password. RACF: The RACF 
alter authority to the cluster or to the catalog 
is required. 





. Data space, specify the catalog's update- or 
higher-level password. RACF: The RACF alter 
authority to the catalog is required. 


® Generation data group, specify the catalog's 
update- or higher-level password. RACF: The RACF 
alter authority to the GDG base or to the catalog 
| is required. 


e Non-VSAM entry, specify the catalog's update- or 
| higher-level password. RACF: The RACF alter 

| authority to the non-VSAM data set or to the 
catalog is required. 


e Page space, specify the entry's master password, 
or the catalog's master password. RACF: The RACF 
alter authority to the page space or to the 
catalog is required. 


@ Path, specify the entry's master password, or the 
catalog's master password. RACF: The RACF alter 
authority to the path or to the catalog is 
required. 


& User catalog, specify the entry's master password 
with the entryname so that access method services 
does not issue a prompting message to the operator 
or TSO terminal user. RACF: The RACF alter 
authority to the user catalog is required. 


Optional Parameters 


ALIAS | ALTERNATEINDEX| CLUSTER] 
GENERATIONDATAGROUP | NONVSAM | PAGESPACE | 
PATH! SPACE | USERCATALOG 
specifies the type of object or entry to be deleted. SPACE 
is required to delete a data space, and USERCATALOG is 
required to delete a catalog. 


ALIAS 
specifies that the entry to be deleted is an alias 
entry. 


ALTERNATEINDEX 
specifies that the object to be deleted is an 
alternate index and its data and index entries. 


When a path entry is associated with the alternate 
index, the path entry is also deleted. 


When the alternate index has the attribute that is 
still to be upgraded and it is the only such alternate 
index associated with the base cluster, the base 
cluster's upgrade set entry is also deleted. 


Abbreviation: AIX 


CLUSTER 
specifies that the object to be deleted is a cluster, 
its associated data and index entries, and any related 
paths and alternate indexes. 
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DELETE 


If the cluster is defined in a recoverable catalog, 
DELETE requires the catalog recovery volume for the 
cluster to be mounted. If the CRA volume is not 
available, then any volume with the required CRA 
volume serial number satifies DELETE's requirements. 


Abbreviation: CL 


GENERATIONDATAGROUP 


specifies that the entry to be deleted is a generation 
data group entry. To delete a generation data group 
that is not empty, you must specify the FORCE 
parameter. 


Abbreviation: GDG 


NONVSAM 


specifies that the entry to be deleted is a non-VSAM 
data set entry. 


If the non-VSAM data set has aliases, all of its alias 
entries are deleted. 


If the non-VSAM data set is partitioned, you can 
delete one of its members by specifying 
pdsname(membername). 


RACF commands can be used to specify an ERASE 
attribute in a generic or discrete profile for a 
non-VSAM data set. Use of this attribute renders all 
allocated DASD tracks unreadable before space on the 
volume is made available for reallocation. Refer to 
the appropriate RACF publications for information 
about how to specify and use this facility. 


Abbreviation: NVSAM 


PAGESPACE 


PATH 


SPACE 


specifies that an inactive page space is to be 
deleted. A page space is identified as "active" 
during the operator's IPL procedure. 


Abbreviation: PGSPC 


specifies that a path entry is to be deleted. No 
entries associated with the path are deleted. 


specifies that all empty VSAM data spaces ona volume 
are to be deleted. This parameter is required when 
you want to delete the volume's empty data spaces. 


To delete a data space that is not empty, you must 
specify both the SPACE parameter and the FORCE 
parameter. 


If all data spaces on a volume have been deleted and 
the volume is not a candidate or catalog volume, its 
volume entry is also deleted. 


Note: When a volume entry in the catalog is deleted, 
VSAM's ownership of the volume is relinquished. When 
the catalog that owns the volume is recoverable, the 
data space that contains the volume's recovery area is 
not deleted unless all other data spaces on the volume 
have ata deleted. CRAs must be deleted in a separate 
command. 


Abbreviation: SPC 


USERCATALOG 


specifies that the object to be deleted is a user 
catalog. ’ 
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The catalog connector entry in the master catalog is 
deleted. If the user catalog has aliases, all the 
aia alias entries in the master catalog are 
eleted. 


To delete a user catalog when it is empty Cthat is, it 
contains only its self-describing entries and its 
volume's volume entry), you must specify USERCATALOG. 
To delete a user catalog that is not empty, you must 
specify both USERCATALOG and FORCE. 


Note: The JOBCAT/STEPCAT is ignored for this command. 
EXPORT DISCONNECT must be used to delete a user 
catalog entry from a user catalog. A master catalog 
for another system is considered to be a user catalog 
by the processing system. 


Abbreviation: UCAT 
CATALOG( catnamel /password] } 


specifies the name of the catalog that contains the entries 
to be deleted. For information about the order in which 
catalogs are searched, see "Order of Catalog Search for 
DELETE™ on page 17 


Note: This parameter cannot be used to delete a user 
catalog. 


identifies the catalog that contains the entry to be 
deleted. 


specifies the password of the catalog that contains 
the entries to be deleted. 


If entries to be deleted are password-protected and 
the catalog is also password-protected, a password 
must be supplied either through CATALOG or with the 
name of each entry to be deleted. The password that 
must be specified for each entry type is given under 
the description of the entryname parameter. 


If a password is supplied through the CATALOG 
parameter, it takes precedence over any password 
supplied with the entryname parameter and is used for 
all entries to be deleted. 


A JOBCAT or STEPCAT DD statement may be needed when 
dynamic allocation is required, because the name of 


the catalog cannot be passed to dynamic allocation via 
the CATALOG parameter. 


Abbreviation: CAT 


ERASE | NOERASE 
specifies whether the data component of a cluster or 
alternate index to be deleted is to be erased, that is, 
overwritten with binary zeros. 


This parameter will override whatever was coded when the 
cluster or alternate index was defined or last altered. 
This parameter should be specified only when a cluster or 
an alternate index entry is to be deleted. When you 
specify ERASE, you must identify the catalog of the entry 
that is still to be deleted with a JOBCAT or STEPCAT DD 
statement unless: 


e The entry is in the master éntalog: or 


e The first qualifier in the entry's qualified name is 
the catalog’s name or alias. 
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ERASE 
specifies that the data component is to be overwritten 
with binary zeros when the cluster or alternate index 
is deleted. If ERASE is specified, the volume that 
contains the data component must be mounted. 


Abbreviation: ERAS 


NOERASE 
specifies that the data component is not to be 
overwritten with binary zeros when the cluster or 
alternate index is deleted. 


Abbreviation: NERAS 


FILE(ddname) 


specifies the name of the DD statement that identifies: 


e The volume that contains a unique data set to be 
deleted. 


e The partitioned data set from which a member Cor 
members) is to be deleted. 


e The data set to be deleted if ERASE is specified. 
@ The volume that contains the data space to be deleted. 


@ The catalog recovery volume(s) when the entry being 
deleted 15 ina recoverable catalog. If the volumes 
are of a different device type, concatenated DD 
statements must be used. (The catalog recovery volume 
is the volume whose recovery space contains a copy of 
the entry being deleted.) (For more details on catalog 
recovery volume pe requirements, see 


® The volume(Cs) owned by the catalog when you delete a 
catalog using the FORCE option. 


If you do not specify FILE and VSAM requires access to a 
volume or volumes during the delete processing, VSAM will 
attempt to dynamically allocate the volumes. When ERASE is 
specified and FILE is not specified, the entryname will 
attempt to be dynamically allocated. Dynamic allocation 
requires that the volume(s) must be mounted as permanently 
resident or reserved. 


When more than one volume is to be identified (for example, 
a multivolume data set), FILE identifies the DD statement 
that specifies all volumes. If in any of the above cases 
the volumes are of a different device type, concatenated DD 
statements must be used. All volumes that contain 
associations to a cluster being deleted must also be 
included on the ddcard referenced by the FILE parameter. 


When deleting multivolume non-VSAM data sets with the 
SCRATCH option, DELETE SCRATCH processing will require 
access to each volume in the entry's cataiog record before 
the scratch can be issued. This will require either all 
volumes to be mounted, online, and allocable to the job, or 
the use of the FILE parameter specifying a DD statement 
allocating at least one mountable unit Cnot permanently 
resident or reserved). Deferred mount must be specified on 
the DD statement so that allocation will flag the UCB to 
allow demount/mount requests to be issued for the unit as 
required during delete processing. If access to the 
volumes cannot be provided, then DELETE NOSCRATCH can be 
used to uncatalog the non-VSAM data set and the user will 
assume the responsibility of scratching the format-l DSCBs 
from all the volumes. 
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FORCE | NOFORCE 


specifies whether objects that are not empty should be 


deleted. 


FORCE 


allows you to delete data spaces, generation data 
groups, and user catalogs without first ensuring that 
these objects are empty. 


If you delete a data space using FORCE: 


All VSAM data spaces on the volume(s) are 
scratched from the VTOC. VSAM's ownership of the 
volume(s) is given up. 


Before the data spaces are scratched, VSAM 
verifies that no VSAM clusters on the volume are 
open. The clusters remain cataloged, but their 
entries are marked unusable. Subsequently, you 
can delete the cluster from the catalog. 


You cannot specify FORCE to delete the space ona 
volume that contains the VSAM master catalog or a 
user catalog. 


You must supply the master password of the catalog 
that contains the volume's entry. 


If you delete a generation data group using FORCE: 


The GDG entry is deleted even though it might 
point to non-VSAM entries in the catalog. 


Each non-VSAM data set entry pointed to by the GDG 
base entry is deleted before the GDG base entry is 
deleted. However, the non-VSAM data set's space 
and contents on the volume are undisturbed. The 
data set can be located with its DSCB in the 
volume's VTOC. 


If you delete a user catalog using FORCE: 


The catalog is deleted even though it contains 
catalog entries for objects that have not been 
deleted. All cataloged objects are automatically 
deleted, but the contents of each cluster and 
alternate index are not erased. 


Before data spaces are deleted, VSAM verifies that 
no VSAM clusters on the volume are open. All data 
spaces are deleted from each volume owned by the 
catalog. The volumes are then available to be 
used by the system or to be assigned to other VSAM 
catalogs. 


VSAM clusters and alternate indexes, even though 
they might reside in unique data spaces, cannot be 
located, because the data space's DSCB is 
scratched when the catalog is deleted. 


Non-VSAM data set entries in the catalog are 
deleted, but the non-VSAM data set's space on the 
volume is undisturbed. The non-VSAM data set can 
be located with its DSCB in the volume's VTOC. 


You must supply the master password of the catalog 
being deleted. 


Abbreviation: FRC 
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am, 


DELETE 


NOFORCE 7 3 | , 
causes the DELETE command to terminate when you 
request the deletion of a data space generation data 
group, or catalog that is not empty. 


Abbreviation: NFRC 
PURGE | NOPURGE 


specifies whether the entry is to be deleted regardless of 
the retention period specified. This parameter cannot be 
used if a data space entry is to be deleted. 


PURGE 
specifies that the entry is to be deleted even if the 
retention period, specified in the TO or FOR 
parameter, has not expired. 


Abbreviation: PRG 


NOPURGE 
specifies that the entry is not to be deleted if the 
retention period has not expired. 


Abbreviation: NPRG 
SCRATCH | NOSCRATCH 


specifies whether a data set is to be removed from the VTOC 
of the volume on which it resides. This parameter can only 
be specified fora cluster, an alternate index, a page 
space, or a non-VSAM data set. 


SCRATCH | | 
specifies that a non-VSAM data set or a data space is 
to or removed from the VTOC of the volume on which it 
resides. 








When SCRATCH is specified for a cluster, alternate 
index, or page space defined with the UNIQUE 
attribute, the entry for the data set is removed from 
the VTOC. For a cluster, alternate index, or page 
space defined with the SUBALLOCATE attribute, the 
entry is deleted from the catalog and thus removed 
ey ae data space. The entry is not removed from 

e . 


When you specify SCRATCH, you must identify the 
catalog of the entry to be deleted with a JOBCAT or 
STEPCAT DD statement, unless the entry is in the 
master catalog, or the first qualifier in the entry's 
qualified name is the catalog's name or alias, or the 
FILE parameter is specified. 


To remove the format-l DSCB from the VTOC you should 
ana SCRATCH function of the OS/VS IEHPROGM 
utility. 


Note: If you specify SCRATCH when deleting a non-VSAM 
data set that was defined with a device type named by 
the user, the DELETE will fail. 


Abbreviation: SCR 

NOSCRATCH 
specifies that the entry is to be deleted from the 
catalog only, without mounting the volume that 
contains the object defined by the entry. 
You should specify NOSCRATCH for the following: 


° If the format-1 DSCB of a non-VSAM data set has 
already been scratched from the VTOC. 
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e If you are deleting a non-VSAM data set that was 
defined with a device type named by the user (for 
example, SYSDA). 


NOSCRATCH cannot be specified for VSAM clusters, 
pct ela ly indexes, or page spaces in VSAM recoverable 
catalogs. 


For more detailed information about the use of DELETE 


NOSCRATCH, see "VSAM Catalog Cleanup™ in 


Abbreviation: NSCR 
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Deleting a Non-VSAM Data Set's Entry: Example 1 


In this example, a non-VSAM data set's entry is deleted. The 
SCRATCH parameter is the default. A FILE parameter and its 
associated DD statement are provided to allocate the data set's 
volume. In this example, dynamic allocation is not used to 
provide catalog or volume allocation. 


~S/DELETS JOB 


//STEP1 EXEC PGM=IDCAMS 
f/DD1 DD VOL=SER=VSERO2,UNIT=DISK, DISP=OLD, 
// DSNAME=EXAMPLE.NONVSAM 
//7SYSPRINT DD SYSOUT=A 
S/SYSIN DD ® 
DELETE - 
EXAMPLE.NONVSAM - 
FILE (DDI) - 


PURGE - 
CATALOGCUSERCAT4/USERUPPW) 
7% 


The DELETE command deletes the non-VSAM data set 
EXAMPLE.NONVSAM. Its parameters are: 


® EXAMPLE.NONVSAM, which is the entryname of the object to be 
deleted. 


@ FILE, which specifies the ddname of a DD statement that 
describes the non-VSAM data set's volume and causes it to be 
mounted. When the data set is deleted, its DSCB entry in 
the volume’s VTOC is removed. 


e PURGE, which specifies that the non-VSAM data set's 
retention period or date is to be ignored. 


e CATALOG, which identifies the catalog that contains the 
entries, USERCATG, and its update password, USERUPPNH. 
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Deleting a Key-Sequenced VSAM Cluster in a Catalog: Example 2 


In this example, a Kkey~sequenced cluster is deleted. Alternate 
indexes and paths related to the key-sequenced cluster are 
deleted automatically by access method services. Access method 
services dynamically allocates the Key-sequenced data set so 
| ee ae data can be overwritten Cas specified by the ERASE 
option). 


//DELETI JOB rae 
4/7 JOBCAT DD DSN=D27UCAT2, DISP=SHR 
//STEPI EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
S/ASYSIN DD ® 
DELETE - 

D40.EXAMPLE.KSDS1 - 

PURGE - 

ERASE - 

CATALOGC D27UCAT2/USERMRPW) 
7% 


Job control language statement: 


e JOBCAT DD, which makes a catalog available for the job: 
D27UCAT2. 


The DELETE command deletes the Key~sequenced VSAM cluster from 
the D27UCAT2 catalog. Its parameters are: 


e D460.EXAMPLE.KSDS1, which is the entryname of the object 
oe deleted. DGO0.EXAMPLE.KSDS1 is a key-~sequenced VSAM 
cluster. 


e PURGE, which specifies that the cluster is to be deleted 
regardless of its retention period or date. 


® ERASE, which specifies that the cluster's data component is 
to be overwritten with binary zeros, regardless of a NOERASE 
attribute that might have been specified when the cluster 
was defined or altered. 


e CATALOG, which identifies the catalog that contains the 
cluster's entries, D27UCAT2. The catalog's master password 
is required, unless the entry's master password is specified 
with the entryname. 
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Deleting an Entry-Sequenced VSAM Cluster in a VSAM Catalog and All Empty Data Spaces 


On a Volume: Example 3 


In this example, an entry-sequenced VSAM cluster is deleted. 
Alternate indexes and paths related to the entry~sequenced 
cluster are automatically deleted by access method services. 
Next, all empty VSAM data spaces on volume VSERO3 are deleted, 
and the volume's volume entry is deleted. 


//DELET2 JOB... 
4/7 JOBCAT DD DSNAME=D27UCAT2, DISP=OLD 
//STEPI EXEC PGM=IDCAMS 


//DD2 DD VOL=SER=VSERO3,UNIT=DISK, DISP=O0LD 
//SYSPRINT DD A ae A 
//7SYSIN DD 
DELETE - 
EXAMPLE.ESDS2/ESD2MRPW - 
PURGE —- 
CLUSTER 
DELETE - 
VSERO3 - 
SPACE - 
FILE (DD2) 
1% 


Job control language statement: 


e JOBCAT DD, which makes a catalog available for the job: 
D27UCAT2. 


The first DELETE command deletes the only VSAM cluster on volume 
VSERO3. The DELETE command's parameters are: 


e EXAMPLE.ESDS2, which is the entryname of the cluster to be 
deleted, and ESD2MRPW, which is the cluster's master 
password. 


@ PURGE, which specifies that the cluster is to be deleted 
regardless of its retention period or date. Alternate 
indexes and paths related to the entry-~sequenced cluster are 
sper deleted, regardless of their retention periods or 
dates. | 


e CLUSTER, which specifies that the entryname EXAMPLE.ESDS2 
identifies a VSAM cluster entry. 


The second DELETE command causes VSAM to examine each data space 
cataloged in the volume's entry. If the data space is empty, it 
is deleted. VSAM deletes the volume entry when there are no 
data spaces cataloged in it, and when there are no data sets 
identified that specify the volume as a candidate volume. VSAM 
also updates the volume's VTOC to reflect the deleted data 
spaces. The DD2 DD statement ensures that volume VSERO3 is 
mounted when its data spaces are deleted. 


In this example, JCL has been used instead of allowing access 
method services to dynamically allocate the volume. If the 
volume were mounted as permanently resident or reserved, access 
method services could dynamically allocate the volume without 
the need of JCL or the FILE parameter. The DELETE command's 
parameters are: 


e VSER0O3, which identifies the volume that contains empty VSAM 
data spaces. 


° SPACE, which specifies that the entryname identifies a 
volume entry. When a volume's data spaces are to be 
deleted, the SPACE parameter is required. 


e FILE, which specifies the ddname of a DD statement that 
describes the VSAM volume and causes it to be mounted. 
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Deleting Two Key-Sequenced Clusters in a Catalog: Example 4 


In this example, two key~sequenced clusters, D4G0.MYDATA and 
ENTRY, are deleted from a catalog. This example illustrates how 
more a one eararesed object is deleted with a single DELETE 
comman 


//DELETS JOB re 

7/7 SJOBCAT DD DSNAME=USERCATS, DISP=SHR 
//STEPI EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

S/3SYSIN DD ¥ 


T _ 
C(D40.MYDATA - 
ENTRY) - 
PURGE - 
CLUSTER 





7% 


Job control language statement: 


e re ae which makes the catalog USERCATS available for 
e job. 


The DELETE command deletes the key~sequenced clusters DG0.MYDATA 
and ENTRY. The high-level qualifier of the object DG0.MYDATA 
causes the catalog D27UCAT1 to be searched, because it is 
assumed that D460 is an alias of the catalog D27UCAT1L. The 
object ENTRY is found in the catalog USERCAT3, which is made 
available to the job through the JOBCAT DD statement. Both 
entries will be dynamically allocated so that their respective 
catalog recovery areas can be updated. The DELETE command's 
parameters are: 


e D40.MYDATA and ENTRY, which identify the objects to be 
deleted. DGO.MYDATA and ENTRY are the entrynames of two 
key-~sequenced clusters. It is assumed that neither cluster | | 
is password-protected at this time. If either cluster is ee 
password-protected, the operator is prompted to supply the 
cluster's master password. 


e PURGE, which specifies that the cluster is to be deleted 
regardless of its retention period or date. 


* CLUSTER, which specifies that DG0.MYDATA and ENTRY identify 
cluster catalog records. 


Deleting Nonempty VSAM Data Spaces on a Volume for a VSAM Catalog: Example 5 


In this example, all of the data spaces on volume VSERO5 are 
deleted, whether or not they are empty. All VSAM data spaces on 
the volume are scratched from the VTOC and the ownership of the 
volume is surrendered by the catalog, AMASTCAT. Any clusters or 
alternate indexes contained within the data spaces on volume 
VSERO5 are marked unusable in the catalog. Because all VSAM 
data spaces on the volume are deleted, the volume's catalog 
entry is also deleted. 


//DELET5 JOB 
//STEPI EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 


FORCE - 
CATALOGCAMASTCAT/USERUPPW) 
/X% 
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The DELETE command's parameters are: 


e VSERO5, which identifies the volume with its serial number. 
Because the volume's VTOC must be updated, access method 
services will dynamically allocate the volume. 


e SPACE, which specifies that a volume entry is to be modified 
or deleted. When a volume's data space is to be deleted, 
the SPACE parameter is required. 


8 FORCE, which specifies that all VSAM data spaces on the 
volume are to be deleted, whether or not they are empty, and 
that volume ownership is to be released. 


e CATALOG, which identifies the catalog that owns the volume, 
sere eal The catalog's update~ or higher-level password is 
required. 


Deleting a User Catalog: Example 6 


In this example, a user catalog is deleted. A user catalog can 
be deleted when it is empty——that is, when there are no objects 
except the catalog's volume cataloged in it. If the catalog is 
not empty, it cannot be deleted unless the FORCE parameter is 
specified. 


//DELET6 JOB oe 
S/STEPI EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
“/SYSIN DD % 
DELETE - 
D27UCATI/USERMRPW - 
PURGE - 
USERCATALOG 
7% 


The DELETE command deletes the catalog. If a VSAM catalog is 
deleted, the volume that contained the catalog is now available 
for ownership by another VSAM catalog. The DELETE command also 
deletes the catalog's user catalog connector entry in the master 
catalog. The DELETE command's parameters are: 


6 D27UCAT1, the name of the user catalog. The catalog's 
update Cor higher level) password is required. 


e PURGE, which specifies that the user catalog's retention 
period or date is to be ignored. If PURGE is not specified 
and the catalog's retention period has not yet expired, it 
will not be deleted. 


e USERCATALOG, which identifies D27UCAT1 as a user catalog. 


Deleting an Alias Entry in a Catalog: Example 7 


In this example, an alias entry, EXAMPLE.NONVSAMI1, is removed 
from catalog USERCATG. 


//DELET7 JOB 


//STEPI EXEC PGM=IDCAMS 
Z/SYSPRINT ODD SYSOUT=A 
“/SYSIN DD x 

DELETE - 


EXAMPLE.NONVSAM1 - 


ALIAS - 
CATALOGCUSERCAT4/USERMRPW) 
7% 


The DELETE command removes an alias entry from catalog USERCAT4. 
Its parameters are: 


e EXAMPLE.NONVSAM1, the entryname of the object to be deleted. 
EXAMPLE.NONVSAM1 identifies an alias entry. 
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ALIAS, which specifies the type of entry to be deleted. 

VSAM verifies that EXAMPLE.NONVSAM1 is an alias entry, then 
deletes it. If EXAMPLE.NONVSAM] identified another entry by 
mistake, VSAM would not delete the entry, but would note the 
discrepancy with a message to the programmer. 


CATALOG, which identifies the catalog that contains the 
entry, USERCAT4, and its master password, USERMRPNW. 


Deleting Generically Named Entries in a Catalog: Example 8 


In t 
"GEN 
simp 
this 
name 


77 
47 
17 
17 
17 


/X 
Job 


The 
entr 
USER 


his example, each catalog entry with the name 

ERIC.*.BAKER™ is deleted, where "X" is any l- to &8-character 
le name. The name "GENERIC.*®.BAKER™ is a generic name, and 
example shows how all catalog entries with the same generic 
are deleted. 


DELETS JOB... 

JOBCAT DD DSNAME=USERCAT4, DISP=OLD 
STEP1 EXEC PGM=IDCAMS 

SYSPRINT DD SYSOUT=A 


SYSIN DD x 
DELETE - 
GENERIC.®.BAKER - 
PURGE - 


CATALOGCUSERCATS/USERMRPW) 


control language statement: 


JOBCAT DD, which makes a catalog available for this job: 
USERCATG. 


DELETE command removes all entries Cand their associated 
ies) with the generic name "GENERIC.*.BAKER” from catalog 
CAT4. Its parameters are: 


GENERIC.®.BAKER, a generic name, identifies all catalog 
entries with the name GENERIC.*. BAKER. 


PURGE, which specifies that each entry is to be purged 
regardless of the retention period or date specified when it 
was defined. 


CATALOG, which identifies the catalog that contains the 
entries, USERCAT4, and its master password, USERMRPHW. 


List a Generation Data Group's Entries, Then Delete the Group and Its Data Sets in a 


Catalog: Example 9 


In t 
asso 


his example, a generation data group, GDGO1, and its 
ciated (generation data set) entries are listed. Next, the 


only generation data set in the group is deleted. Finally, the 


gene 


/f 
17 
17 
17 


ration data group base catalog entry is deleted. 


DELET9 JOB ‘ 
STEP] EXEC PGM=IDCAMS 
SYSPRINT DD SYSOUT=A 
SYSIN DD % 
LISTCAT - 
ENTRIESCGDGO1) - 
ALL 


DELETE - 
GDGO1.GOO001V00 - 
PURGE 


DELETE - 
GDGO1 - , 
GENERATIONDATAGROUP - 
PURGE 


7% 
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Because no catalog was specified in a CATALOG parameter or with 
a JOBCAT or STEPCAT DD statement, VSAM assumes all entries 
required for this command sequence are in the master catalog. 


The LISTCAT command lists the generation data group GDGOl1 and 
its associated generation data set entries. Its parameters are: 


e ENTRIES, which specifies that the entry GDGO1 is to be 
listed. Because the entry GDGO1 is a generation data group 
entry, its associated generation data set's Cnon-VSAM) 
entries are also listed. In addition, if one of the 
generation data sets has aliases, the alias entries 
associated with the generation data set's entry are listed. 


e ALL, which specifies that all fields are to be listed. 


The first DELETE command removes the non-VSAM data set entry for 
the only generation data set in the generation data group: 
GDGO01.GO001V00. Its parameters are: 


e GDG01.GO0001V00, the entryname of the object being deleted. 
GDGO01.GO0001V00 identifies the only generation data set in 
the generation data group GDGOl1. 


e PURGE, which specifies that the generation data set's 
retention period or date is to be ignored. 


The second DELETE command removes the catalog entry of the 
generation data group base from the catalog. Its parameters 
are: 


e GDGO1, the entryname of the object being deleted. GDGOI] 
identifies the generation data group base entry. 


e GENERATIONDATAGROUP, which specifies the type of entry to be 
deleted. VSAM verifies that GDGO1 is a generation data 
group entry, then deletes it. If GDGO1 incorrectly 
specified another type of entry, VSAM would not delete the 
entry, but would note the discrepancy with a message to the 
programmer. 


@ PURGE, which specifies that the generation data group's 
retention period or date is to be ignored. 
Deleting a Member of a Partitioned (Non-VSAM) Data Set in a Catalog: Example 10 
In this example, the MEM] member of partitioned data set 
peg are Aa is deleted. Next, the non-VSAM data set itself 
is deleted. 


//DELET10 JOB re 
// SOBCAT DD DSNAME=USERCAT4, DISP=SHR 


//STEP1 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD 3 

DELETE - 


EXAMPLE.NONVSAM2CMEM1) - 

CATALOGCUSERCAT4/USERMRPW) 
DELETE - 

EXAMPLE.NONVSAM2 - 


PURGE - 
CATALOGCUSERCAT4/USERMRPW) 
7% 


Job control language statement: 


e JOBCAT DD, which makes a catalog available for this job: 
USERCATS. 
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DELETE 


The first DELETE command deletes one of the members of a 
partitioned data set, EXAMPLE.NONVSAM2(MEM1), from the user 
catalog, USERCAT4. Its parameters are: 


e  EXAMPLE.NONVSAM2CMEM1), which is the entryname of one of the 
members of the partitioned Cnon-VSAM) data set, 
ae The entryname identifies the object to be 
eleted. | 


e CATALOG, which identifies the catalog that contains the 
entry, USERCAT4, and its master password, USERMRPW. 





The second DELETE command deletes all remaining members, as well 
as the data set itself, of the partitioned non-VSAM data set 
EXAMPLE.NONVSAM2. Its parameters are: 


e EXAMPLE.NONVSAM2, which is the entryname of the object to be 
deleted. 


e PURGE, which specifies that the non-VSAM data set's 
retention period or date is to be ignored. If PURGE had not 
been specified and the non-VSAM data set's retention period 
has not yet expired, VSAM would not delete its entry. 


e CATALOG, which identifies the catalog that contains the 
entry, USERCATS, and its master password, USERMRPW. 


In the second part of this example, the DSCB entry in the 
volume'’s VTOC is removed. Dynamic allocation is used to 
allocate the data set's volume. 

Deleting a Page Space: Example 11 
In this example, page space SYS]1.PAGE2 is deleted. 


//DELETI1 JOB... > % 
//STEPI EXEC PGM=IDCAMS — 


//SYSPRINT DD SYSOUT=A 
S7SYSIN DD % 
DELETE - 
SYS1.PAGE2/MASTMPW1 —- 
PURGE - 
PAGESPACE 
7% 


The DELETE command removes the page space entry, SYS1.PAGE2, 
from the master catalog. Its parameters are: 


6 SYS1.PAGE2, the entryname of the object to be deleted. 
SYS1.PAGE2 identifies a page space entry. The catalog's 
update- or higher-level password is also required. 


e PURGE, which specifies that the page space entry is to be 
deleted regardless of the retention period or date specified 
when it was defined. 


e PAGESPACE, which specifies the type of entry to be deleted. 
VSAM verifies that SYS1.PAGE2 is a page space entry, then 
deletes it. If SYSI1.PAGE2 incorrectly identified another 
type of entry, VSAM would not delete it, but would send an 
error message to the programmer. 
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EXAMINE 





The EXAMINE command analyzes and reports on the structural 
consistency of the index component and/or data component of a 


key~sequenced data set (KSDS) cluster. The format of the EXAMINE 
command is: 


1) 


SCOR 


r [/ 
ST|NOINDEXTEST] 


CDATATEST | NODATATEST 1 
CERRORLIMIT( value) ] 





EXAMINE PARAMETERS 


Required Parameters 


NAME(clusternamel/password] ) 
specifies which user cluster is to be analyzed for 
structural consistency by EXAMINE. EXAMINE expects the 
user to have specified a particular key-~sequenced data set 
by its cluster name. The appropriate cluster component is 
then selected dynamically during program execution. When 
analyzing a VSAM catalog, use a STEPCAT DD statement to 
point to that catalog and apply a VERIFY DATASET command 
before using the EXAMINE command. A STEPCAT DD statement is 
not required for the master catalog. 


a 
specifies the identification of the key-~sequenced data 
set cluster to be analyzed. 


specifies, optionally, the master password associated 
with a catalog or the control password for a data set. 


Optional Parameters 


INDEXTEST | NOINDEXTEST 
specifies whether or not EXAMINE is to perform tests 
associated with the index component of the cluster. 
INDEXTEST is the default. 


INDEXTEST 
performs tests upon the index component of a 
key-sequenced data set cluster. 


Abbreviation: ITEST 


NOINDEXTEST 


does not perform any testing upon the index component 
of a key~sequenced data set cluster. 


Abbreviation: NOITEST 
DATATEST | NODATATEST 
specifies whether or not EXAMINE is to perform tests 


associated with the data component of the cluster. 
NODATATEST is the default. 
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EXAMINE 


DATATEST Re 
performs tests upon the data component of a a 
key-~sequenced data set cluster. NOINDEXTEST and ‘i 7 
Al are specified when only a DATATEST is re 

esired. ne | 





Abbreviation: DTEST 


NODATATEST 
does not perform any testing upon the the data 
component of a Key~sequenced data set cluster. 


! | Abbreviation: NODTEST 


| ERRORLIMIT( value } 

specifies a numeric limit Cvalue) to the number of errors 

| for which detailed EXAMINE error messages are to be printed 

| during program execution. ERRORLIMIT is designed to 

| prevent runaway message output. The default value for 
ERRORLIMIT is 2147483647 errors, but you can specify any 
number between 0 and 21474836497. Note that testing 
continues even though the error limit is reached. 


Abbreviation: ELIMIT 


EXAMINE EXAMPLES 


Examine Both Components of a Key-Sequenced Data Set: Example 1 


This example shows how to get a list of data set structural a OS 
errors that can be used to support problem resolution. 


7/7 EXAMEX2 JOB 
//STEPI EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
“/SYSIN DD % 
EXAMINE - 

NAMECKSDSO1) - 

INDEXTEST - 

DATATEST 
7% 


Use the EXAMINE command to analyze both components of a 
key-~sequenced data set. Its parameters are: 


® NAME, which specifies the cluster name only. The data set 
has no control level password protection. 


@ INDEXTEST, which causes the index component to be examined. 
e DATATEST, which causes the data component to be examined. 


e The default for ERRORLIMIT (it was not specified) allows 
detailed error messages to be printed. 
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EXAMINE 


Examine the Data Component of a VSAM User Catalog: Example 2 


This example shows how to determine whether your VSAM catalog 
has structural errors. 


//EXAMEXS JOB 

//STEPI EXEC PGM=IDCAMS 

S/7STEPCAT DD DSN=VCATO1.VCAT, DISP=SHR 
//7SYSPRINT DD SYSOUT=A 

S7SYSIN DD x 


VERIFY DATASETCVCATO1.VCAT) 
EXAMINE - 
NAMECVCATO1.VCAT) - 
NOINDEXTEST - 
DATATEST —- 
ERRORLIMITC1000) 


7% 


Use the EXAMINE command to analyze the data component of a VSAM 
catalog. Its parameters are: 


NAME, which specifies the catalog name. The catalog must be 
connected to the master catalog. 


NOINDEXTEST, which specifies that the index component is not 
to be examined. 


DATATEST, which causes the data component to be examined. 


ERRORLIMITC1000), which restricts the printing of detailed 
error messages to 1000 errors. 


Note that the STEPCAT DD statement and the VERIFY DATASET 
ee are required when you use EXAMINE against a VSAM user 
catalog. 
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EXPORT DISCONNECT 


EXPORT DISCONNECT 


The EXPORT DISCONNECT command disconnects a user catalog. The 
format of this command is: 


EXPORT usercatnamel/password] 
DISCONNECT 


EXPORT DISCONNECT PARAMETERS 





Required Parameters 
usercatnamel/ 


names the user catalog to be disconnected. This parameter 
must be the first parameter following EXPORT. 


When you are disconnecting a user catalog, you must supply 
the update- or higher-level password of the master catalog. 
RACF: The update or higher RACF authority for the master 
catalog is required. 


DISCONNECT 
specifies that a user catalog is to be disconnected. The 
connector entry for the user catalog is deleted from the 
master catalog. Also, the user catalog's alias entries are 
deleted from the master catalog. 


If EXPORT is coded to remove a user catalog connector 
entry, DISCONNECT is a required parameter. The volume that 
contains a VSAM user catalog can be physically moved to the 
system to which the catalog will be connected. 


A JOBCAT/STEPCAT can be used to delete a user catalog a? 
connector entry from a user catalog. Any alias entries 

will also be deleted. In this case, the password should be 

the master password of the user catalog specified in the 
JOBCAT/STEPCAT. 


Note: To make a user catalog available in other systems 
and in the original system, code the IMPORT CONNECT command 
to connect the user catalog to each system to which it is 
oe available, but do not EXPORT DISCONNECT the user 
catalog. 


Abbreviation: DCON 


Mohair 
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EXPORT DISCONNECT 
Export Disconnect of a User Catalog: Example 1 


In this example, the user catalog D27UCAT1 is exported and 
disconnected from the system. Its cataloged objects are no 
longer available to users of the system. 


77EXPORT3 JOB oe 
//STEPI EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
S/SYSIN DD % 
EXPORT - 
D27UCAT1/MASTMPW1 - 
DISCONNECT 





7% 


The EXPORT command removes the user catalog connector entry for 
D27UCAT1 from the master catalog. The catalog becomes 
unavailable to system users until the system programmer 
reconnects it to the system using an IMPORT CONNECT command. 
The EXPORT command's parameters are: 


e D27UCAT1, which identifies the object to be disconnected. 
When a user catalog is disconnected, the master catalog's 
master password is required. 

e DISCONNECT, which identifies the object as a user catalog. 


When a user catalog's connector entry is to be deleted, 
DISCONNECT is required. 
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EXPORT 
EXPORT 


The EXPORT command exports a VSAM cluster or an alternate index. 
The format of this command is: 





entrynamel /password] 

fOUTFILE(ddname} | OUTDATASET(entryname)} 
LERASE | NOERASE] 

CINFILE( 


ddname } 
[ INHIBITSOURCE | NOINHIBITSOURCE 1] 
EINHIBTT TARGET | NOINHIBITTARGET! 
[PURGE | 


NOPURGE] 
[ TEMPORARY | PERMANENT ] 





EXPORT can be abbreviated: EXP 


EXPORT PARAMETERS 


Required Parameters 
entrynamel/password] 


names the cluster or alternate index to be exported. This 
parameter must be the first parameter following EXPORT 


If you are exporting: 


6 A cluster or alternate index, you must supply the 
object's master password. RACF: The alter RACF 
authority to the cluster or alternate index is 
required. 


e A cluster or alternate index with any aed 
password-protected paths defined over them, you 
must supply the master password of the catalog 
containing the objects in order to export the 
protection attributes of all the paths. RACF: 
The alter RACF authority to the catalog is 
required. 


OUTFILE( ddname) | OUTDATASET(entryname) 
specifies the name of the DD statement or the data set that 
is to receive the data being exported. 


OUTFILE(ddname) 
specifies the name of the DD statement of the target 
data set. 


Only the block size for the DCB parameter should be 
specified in the DD statement. The default for block 
size for EXPORT is 2048. Block size may be specified 
in the DD statement to override this default and 
improve performance. 


Abbreviation: OFILE 
OUTDATASET(entryname) 


specifies the name of the target data set. If 
OUTDATASET is specified, an attempt is made to 
dynamically allocate the target data set. The 
characteristics of the target data set are described 
in "For a Target Data Set™ on page 190. 


Abbreviation: ODS 
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EXPORT 
Optional Parameters 


ERASE | NOERASE 
specifies whether the data component of the cluster or 
alternate index to be exported is to be erased (that is, 





overwritten with binary zeros). This parameter overrides 
a iebdat was specified when the object was defined or last 
altered. 


This parameter can be specified only if the object is to be 
Sella exported (that is, deleted from the original 
system). 


ERASE 
specifies that the data component is to be overwritten 
with binary zeros when the cluster or alternate index 
is deleted. If ERASE is specified, the volume that 
contains the data component must be mounted. 


Abbreviation: ERAS 


NOERASE 
specifies that the data component is not to be 
overwritten with binary zeros when the cluster or 
alternate index is deleted. 


Abbreviation: NERAS 


INFILE(ddname) 
specifies the name of the DD statement that identifies the 
cluster or alternate index to be exported. If the cluster 
or alternate index has been defined with a maximum logical 
record length greater than 32760 bytes, EXPORT processing 
terminates with an error message. 


po, In addition to the DD statement for INFILE, you must 
( identify the entry's catalog with a JOBCAT or STEPCAT DD 
statement unless: 


6 The object's entry is in the master catalog, or 


® The first qualifier of the object's name is the 
catalog's name or alias. 


When INFILE and its DD statement are not specified for an 
object that is to be exported, an attempt is made to 
dynamically allocate it. 


Abbreviation: IFILE 


INHIBITSOURCE | NOINHIBITSOURCE 
specifies whether the original data records (the data 
records of the source cluster or alternate index) can be 
accessed for any operation other than retrieval after a 
copy is exported. This specification can later be altered 
through the ALTER command. 


INHIBITSOURCE 
specifies that the source object in the original 
system cannot be accessed for any operation other than 
retrieval. This parameter can be specified only when 
the object is to be temporarily exported CA backup 
copy of the object is made and the object itself 
remains in the original system.) 


Abbreviation: INHS 


NOINHIBITSOURCE 
specifies that the original data records in the 
original system can be accessed for any kind of 
operation. 


Abbreviation: NINHS 


em 
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EXPORT 


INHIBITTARGET | NOINHIBITTARGET 
specifies whether the data records copied into the target 
alternate index or cluster can be accessed for any 
operation other than retrieval after they have been 
imported to another system. This specification can be 
altered through the ALTER command. 


INHIBITTARGET 
specifies that the target object cannot be accessed 
for any operation other than retrieval after it has 
been imported into another system. 


Abbreviation: INHT 


NOINHIBITTARGET 
specifies that the target object can be accessed for 
any type of operation after it has been imported into 
another system. 


Abbreviation: NINHT 
PURGE | NOPURGE 


specifies whether the cluster or alternate index to be 
exported is to be deleted from the original system 

regardless of the retention period specified in a "To or FOR 
parameter when the object was defined. 





This parameter can be specified only if the object is to be 
ere Neal exporeecs that is, deleted from the original 
system 


PURGE 
specifies that the object is to be deleted even if the 
retention period has not expired. 


Abbreviation: PRG 


NOPURGE Ae ee 
specifies that the object is not to be deleted unless 
the retention period has expired. 


Abbreviation: NPRG 


TEMPORARY | 
specifies whether the cluster or alternate index to be 
exported is to be deleted from the original system. 


TEMPORARY 
specifies that the cluster or alternate index is not 
to be deleted from the original system. The object in 
the original system is marked as temporary to indicate 
that another copy exists and that the original copy 
can be replaced. 


To replace the original copy, a portable copy created 
by an EXPORT command must be imported to the original 
system. The IMPORT command deletes the original copy, 
defines the new object, and copies the data from the 
portable copy into the newly defined object. 


Note: Be sure to properly protect the file of the 
+ temporary object if you want to deny unauthorized 
access to that file. 


Abbreviation: TEMP 


PERMANENT 
specifies that the cluster or alternate index is to be 
deleted from the original system. Its storage space 
is freed. If its retention period has not yet oa 
expired, you must also code PURGE. 


Abbreviation: PERM 
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EXPORT 
EXPORT EXAMPLES 


Exporting a Key~Sequenced Cluster: Example 1 


In this example, a key-~sequenced cluster, D40.EXAMPLE.KSDSI, is 
exported from a user catalog, D27UCAT1. The cluster is copied 
to a portable file, TAPE2, and its catalog entries are modified 
to prevent the cluster's data records from being updated, added 
to, or erased. 


/7EXPORT1 JOB . 
//STEPI EXEC PGM=IDCAMS 
//7RECEIVE DD DSNAME=TAPE2,UNIT=CTAPE,, DEFER), 
17 DISP=NEW, VOL=SER=003030, 
47 DCB=C(CBLKSIZE=6000, DEN=3),LABEL=(€1,5L) 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD x 
EXPORT —- 

D40.EXAMPLE.KSDS1 - 

OUTFILECRECEIVE) - 

TEMPORARY - 

INHIBITSOURCE 
7% 


Job control language statement: 


e RECEIVE DD, which describes the portable file, a magnetic 
tape file, that is to receive a copy of the cluster'’'s 
records. The DCB BLKSIZE parameter overrides the EXPORT 
default of 2048 to improve performance. 


The EXPORT command copies the key~sequenced cluster, 
D4G0.EXAMPLE.KSDS1, to a portable file, TAPE2, and modifies the 
cluster's catalog entries (its cluster, data, and index 
entries). Access method services attempts to dynamically 
allocate DG0.EXAMPLE.KSDS1. Because the high-level qualifier of 
the cluster name is the name of the alias of D27UCAT2, the 
cluster can be allocated without specifying a JOBCAT or STEPCAT 
DD statement. The EXPORT command's parameters are: 


e D40.EXAMPLE.KSDS1, which identifies the cluster to be 
exported. Because the cluster is not password-protected, no 
password is provided with the cluster's entryname. 


e OUTFILE, which points to the RECEIVE DD statement. The 
RECEIVE DD statement describes the portable file, TAPE2, 
that is to contain a copy of the cluster. 


@ TEMPORARY, which specifies that the cluster is not to be 
deleted. The cluster's catalog entry is marked "temporary" 
to indicate that another copy of the cluster exists and that 
the original copy can be replaced. (See the IMPORT Example, 
"Importing a Key-Sequenced Cluster."™) 


6 INHIBITSOURCE, which specifies that the copy of the cluster 
at remains in the original system, as a result of 
TEMPORARY, cannot be modified. User programs are allowed 
only to read the cluster's records. 
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EXPORT 





Exporting an Entry-Sequenced Cluster: Example 2 


In this example, an entry-~sequenced cluster is exported to a 
portable file and then deleted from the system. 


/7EXPORT2 JOB ee 
//STEPI EXEC PGM=IDCAMS 
//RECEIVE DD DSNAME=TAPE1,UNIT=CTAPE,, DEFER), 
// VOL=SER=001147,LABEL=C€1,5L),DISP=NEW 
7/7SYSPRINT DD SYSOUT=A 
S/SYSIN DD X 
EXPORT —- 
D50.EXAMPLE.ESDS1 - 
OUTFILECRECEIVE) - 
PURGE 
7% 


Job control language statement: 


@ RECEIVE DD, which describes the portable file, TAPEl, that 
on fe contain a copy of the exported entry-~sequenced 
cluster. 


The EXPORT command copies the entry-~sequenced cluster, 
D50.EXAMPLE.ESDS1, to a portable file, TAPE]. The cluster is 
deleted from the system after it is copied into the portable 
file. Access method services attempts to dynamically allocate 
D50.EXAMPLE.ESDS1. Because the high-level qualifier of the 
cluster is the name of the alias of the catalog D27UCAT2, the 
cluster will attempt to be dynamically allocated without 
specifying a JOBCAT or STEPCAT DD statement. The EXPORT 
command's parameters are: | 


e D50.EXAMPLE.ESDS1, which identifies the entry~sequenced 
cluster to be exported. When a cluster is exported, its 
master password is required if it is password-protected. 


e OUTFILE, which points to the RECEIVE DD statement. Th 


e 
RECEIVE DD statement describes the portable data set, TAPEI, 


that is to receive a copy of the cluster. 


° PURGE, which allows the cluster to be deleted regardless of 


its retention period or date. 


Because EXPORT defaults to PERMANENT, access method services 


assumes the cluster is to be deleted after TAPE1 contains a copy 


of it 


Because EXPORT defaults to NOINHIBITTARGET, access method 
services assumes the cluster can be updated (by users of the 
other system) when it is imported to another system. 
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EXPORTRA PARAMETERS 


Required Parameters 








EXPORTRA 


The EXPORTRA command recovers VSAM and non-VSAM catalog entries 

from catalog recovery areas, and recovers data for VSAM clusters 
and alternate indexes by means of catalog recovery areas. This 

command is for use with , 


The format of the EXPORTRA command is: 


EXPORTRA| OUTFILE(ddname) 
CRA( 


(ddnamel 
CALL£ INFILE( ddname2)1] 
ENTRIES ( 
Centrynamel ddname3]) 
[lentrynamel ddname3])...1)] 
NONE} ) 
E(ddnamel...)...]) 
[FORCE | NOFORCE] 
C[MASTERPW( password)] 





EXPORTRA can be abbreviated: XPRA 


OUTFILE(ddname) 


CRAC 
( 


identifies the DD statement that describes the data set 
Cusually a movable disk pack or magnetic tape reel) that is 
to contain a copy of the VSAM objects and catalog entries 
identified with the CRA parameter. 


With the exception of block size, the data set 
characteristics of the target data set that is to contain 
the cluster to be exported should not be specified. Block 
Size is defaulted by the EXPORTRA command to 2048. Block 
Size may be specified in the DD statement to override this 
default and improve performance. 


The characteristics of the target data set are described in 
"For a Target Data Set™ on page 10 


Abbreviation: OFILE 


ddnamel 
{CALLE INFILE(ddname2)1] 


ENTRIES ( 
Centrynamel ddname3]) 
[Centryvnamel ddname3])...1)| 
NONE} } - 
The CRA parameter and its subparameters describe the 
catalog recovery area(s) to be referred to, identify the 
specific entries to be copied from the catalog recovery 
area, and specify the volumes that contain the entries’ 
data. A separate set of subparameters is specified to 
describe each catalog recovery area to which it refers. 


identifies the DD statement that describes a volume to 
whose catalog recovery area is referred. Each ddnamel 
you specify is followed by one of the following 
subparameters, which specifies the action to be taken 
with regard to the catalog recovery area: 
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EXPORTRA 
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ALL 


specifies that each entry in ddnamel's catalog 
recovery area is to be copied to the OUTFILE data set. 
In addition, the contents (that is, data records in 
logical sequential order) of each VSAM cluster and 
alternate index are copied, following the copy of the 
catalog recovery area entry. 


If any of these VSAM clusters or alternate indexes has 
data that resides on volumes other than that 
identified via ddnamel, you use INFILE to describe all 
the volumes. 


INFILE(ddname2) 


identifies the DD statement that describes multiple 
volumes to be used in the recovery process. INFILE is 
required if the VSAM clusters and/or alternate indexes 
whose entries are contained in ddnamel's catalog 
recovery area reside on multiple volumes. The ddname2 
DD statement should include all volumes containing the 
data set, including the recovery area volume. 


Abbreviation: IFILE 


ENTRIES( 
Centrynamef ddname3]) 
CCentrynamel ddname3])...]1) 


NONE 


names each entry in the catalog recovery area that is 
to be copied to the OUTFILE data set. All other 
entries in the catalog recovery area are not copied. 


entryname 
names an object whose catalog entry is contained 
in the ddnamel volume's catalog recovery area. 
You can specify the entryname of the following 
entry types: alternate index, cluster, and 
non-VSAM. 


When you specify a cluster entry, the cluster's 
data and index entries and all associated path 
entries are also copied. In addition, the 
cluster's contents (that is, its data records, in 
logical sequential order) are copied, following 
the copies of the cluster's catalog entries. 


When you specify an alternate index entry, the 

alternate index's entries and contents and all 

associated path entries are copied as though it 
were a key~sequenced cluster. 


identifies the DD statement that describes each 
volume that contains part of the cluster or 
alternate index. ddname3 is ignored when 
specified for a non-VSAM entry. 


ddname3 is required when the entry is a VSAM 
cluster or alternate index whose data resides on 
volumes other than the volume identified with the 
ddnamel DD statement. The ddname3 DD statement 
must also include the volume referenced by the 
ddnamel DD statement. 


Abbreviation: ENT 


specifies that no object in the volume’s catalog 
recovery area is to be copied. You must specify 
ddnamel NONE for each volume referenced in a ddname2 
or ddname3 DD statement if you do not want the entries 
in its catalog recovery area to be copied. 


Note: If ddname2 contains both multiple volume and 
Single volume entries, a NONE statement is required to 
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Optional Parameters 


ac pt 








EXPORTRA 


prevent processing of the single volume entries that 
exist on the second and subsequent volumes. The NONE 
parameter must be specified before the ALL parameter. 
(See "Using EXPORTRA for All Entries on Multiple 
Volumes: Example 2" on page 182.) 


FORCE | NOFORCE 


specifies whether the catalog entry's copy is to be copied 


from the catalog recovery area, even though the copy itself 
might be inaccurate. 


FORCE 


specifies that the object's catalog entry copy is 
copied from the volume's catalog recovery area, even 
though a loss of data integrity might result. Time 
stamp and extent mismatches are ignored. 


Abbreviation: FRC 


NOFORCE 


specifies that the catalog recovery area's copy is not 
copied if it is not accurate, and the EXPORTRA command 
terminates with an error message. 


Abbreviation: NFRC 


MASTERPW( password) 
specifies the master catalog's master password. The master 
catalog'’s master password is required when the master 
catalog is password-protected. RACF: The alter RACF 
authority to the master catalog is required. 


Abbreviation: MRPW 
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EXPORTRA EXAMPLES 


Using EXPORTRA for All Entries on One Volume: Example 1 


This example shows the EXPORTRA function for one volume, V0, 
owned by the VSAM master catalog. All the entries contained in 
the catalog recovery area on VO and the data sets themselves are 
copied to a SAM data set on another disk volume. All the data 
sets reside entirely within the one volume. 


/7EXPORTRA JOB... 
//STEPI EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//NLVO DD UNIT=DISK, VOL=SER=V0,AMP="AMORG’, DISP=OLD 
//NOLOUT DD UNIT=DISK, VOL=SER=333003,DSN=OUT.FILE, 
// DISP=(NEW, KEEP) ,SPACE=(CYL,(5,1)), 
// DCB=BLKSIZE=6000 
“/SYSIN DD % 
EXPORTRA —- 
OUTFILECVOLOUT) - 


CRA C€ - 
CVLVO ALL)) 
ie 


Job control language statements: 


e VLVO DD, which identifies and allocates the volume whose 
catalog recovery area contents are to be copied. The data 
sets reside wholly within the one volume. 


® VOLOUT DD, which identifies the sequential file that is to 
‘receive the copied data sets and catalog recovery records. 
The DCB BLKSIZE parameter overrides the EXPORTRA default of 
2048 to improve performance. Be ae 


The EXPORTRA command copies everything appearing in the catalog 
recovery area of volume V0. The EXPORTRA command parameters 
are: 


e OUTFILE, which is required and identifies the sequential 
access method (SAM) non-VSAM data set that is to receive the 
copied information. 


® CRA, which is required and identifies the catalog recovery 
area and volume from which the copy is to take place. VLVO 
identifies the DD statement for the catalog recovery volume. 
The ALL subparameter specifies that all entries are to be 
copied from the catalog recovery area. The INFILE 
subparameter is not required, because the data sets are 
contained wholly within the one volume. 


Using EXPORTRA for All Entries on Multiple Volumes: Example 2 


This example shows the EXPORTRA function for one volume owned by 
the VSAM master catalog. All data sets contained on the volume, 
VO, and their corresponding CRA entries describing the data sets 
are copied to a sequential (SAM) data set on a tape volume. The 
catalog recovery area contains data sets which reside on volumes 
Vl and V2 in addition to the recovery volume, VO. The entries 
in the catalog recovery areas of the additional volumes are not 
to be recovered. 
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//7EXPORTRA JOB 
S/STEPI EXEC PGM= IDCAMS 
S/SYSPRINT DD SYSOUT=A 
//NLVO DD UNIT=DISK,VOL=SER=V0,AMP="AMORG', 
Sf DISP=OLD 
//NLVI DD UNIT=DISK,VOL=SER=V1,AMP="AMORG', 
// DISP=OLD 
S/NLV2 DD UNIT=DISK, VOL=SER=V2,AMP="AMORG', 
1? DISP=OLD 
//NOLA DD UNIT=CDISK,33,VOL=SER=(V0,V1,V2), 
// AMP="*AMORG! , DISP=OLD 
//NOLOUT DD DSN=OUT.FILE,LABEL=(€1,SL), 
// DISP=CNEW,KEEP), 
/f UNIT=TAPE,VOL=SER=TAPEOIL, 
// DCB=CBLKSIZE=8192, DEN=3) 
S/SYSIN DD * 
EXPORTRA - 
OUTFILECVOLOUT) - 
CRA ¢ 
(VLVO ALL INFILECVOLA)) 2 
CVLV1 NONE) 
CVLV2 NONE) - 
CVLV1 ALL))D- 
MASTERPNCMCATMRPW) 
/% 


Job control language statements: 


@ VLVO DD, which identifies the volume whose catalog recovery 
area contents are to be exported. 


e VLV1 DD, which identifies a volume containing part of a 
multiple volume data set to be exported and single volume 
data sets to be exported. 


e VLV2 DD, which identifies a volume containing part of a 
multivolume data set to be exported. The catalog recovery 
area contents are not to be exported. 


e VOLA DD, which identifies all the volumes containing the 
data sets to be exported. 


@ VOLOUT DD, which identifies the sequential tape file that is 
to receive the exported data sets and catalog recovery 
records. The DCB BLKSIZE parameter overrides the default of 
2048 to improve performance. 


The EXPORTRA command copies every entry appearing in the catalog 
recovery area of volume V0 and the data sets described by the 
CRA entries. Because they contain part of multivolume data 
sets, two additional volumes, V1 and V2, are referred to, but 
the entries in their catalog recovery areas are not exported. 
The EXPORTRA command parameters are: 


e OUTFILE, which is required and identifies the sequential 
CSAM) non-VSAM data set that is to receive the exported 
information. 


e CRA, which is required and identifies the catalog recovery 
area and volumes from which the entries are to be copied. 
YLVO identifies the DD statement of the recovery volume. 
The ALL subparameter specifies that all entries in the 
catalog recovery area of the volume identified by VLVO are 
to be copied. 


INFILE, which is required because the data sets to be copied 
are contained on multiple volumes. VOLA refers to the DD 
statement that identifies these multiple volumes, including 
the recovery volume. 


VLV1 NONE, which is required to prevent processing of single 
volume entries that exist on this volume that is referenced 
aaa huge subparameter. This subparameter must precede 
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Using EXPORTRA for Selected Entries: 


VLV2 NONE, whic 
identifies is r 


VLV1 ALL is req 





h is required because the volume it 
eferenced in the INFILE subparameter. 


uired and identifies the single volume data 


sets. This subparameter must come after VLV1 NONE. 


e MASTERPW, which 
catalog. This 
is password pro 


This example shows 
from the catalog re 
master catalog. Th 
from the catalog re 
sequential (SAM) da 
of the data sets an 
copied. Two of the 


specifies the master password of the master 
parameter is required when the master catalog 
tected. 


Example 3 


the EXPORTRA function for selected entries 
covery area of one volume owned by the VSAM 
ree data sets and their corresponding entries 
covery area on volume V0 are copied to a 

ta set on another disk volume. The remainder 
d the catalog recovery area entries are not 
selected data sets are multivolume VSAM data 


sets. The data sets and their corresponding entries in the 


catalog recovery ar 
recovered. 


//EXPORTRA JOB 


//STEP1 EXEC 
//SYSPRINT DD 
//NLVO DD 
// VOL 
//NLVI DD 
// VOL 
S/NLV2 DD 
/7/ VOL 
//NOLA DD 
// VOL 
//NOLB DD 
/f VOL 
//NOLOUT DD 
17 DISP= 
//7SYSIN DD 
EXPORTRA - 
OUTFILECV 
CRA ¢€ - 
CVLVO 
CL 
CL 
CL 
CVLV1 
CVLV2 
FORCE 


7% 


Job control languag 


e VLVO DD, which 


area contains the entries for the three VSAM data sets to be 


copied. 


@ VLV1 and VLV2 D 
containing part 
recovery area c 


° VOLA DD, which 
LARGE.DATASET.A 


e VOLB DD, which 


eas of the additional volumes are not 


PGM=IDCAMS 
SYSOUT=A 
UNIT=DISK, AMP="AMORG', DISP=OLD, 


=SER=VO 


UNIT=DISK,AMP="AMORG', DISP=OLD, 


=SER=V1 


UNIT=DISK, AMP=" AMORG* , DISP=OLD, 


=SER=V2 


UNIT=CDISK,3),AMP="AMORG*,DISP=OLD, 


=SER=(V0,V1,V2) 


UNIT=CDISK,2),AMP="AMORG", DISP=OLD, 


=SER=(V0,V1) 


UNIT=DISK, VOL=SER=333003,DSN=OUT.FILE, 
CNEW, KEEP) ,SPACE=(CYL,(5,1)) 
Xx 


OLOUT) - 

ENTRIES € - 
ARGE.DATASET.A VOLA) - 
ARGE.DATASET.B VOLB) - 
ARGE.DATASET.C))) - 


NONE) ~ 
NONE)) - 


e statements: 


identifies the volume whose catalog recovery 


D, each of which identifies a volume 
of a multivolume data set but whose catalog 
ontents are not to be copied. 


identifies the multivolumes of 


identifies the multivolumes of 


LARGE. DATASET .B. 


e VOLOUT DD, which identifies the sequential file that is to 
receive the copied data sets and catalog recovery records. 


The EXPORTRA command exports the three entries CLARGE.DATASET.A, 
LARGE.DATASET.B, and LARGE.DATASET.C) from the catalog recovery 


area on volume VO. 


Because they contain part of multivolume 
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data sets, two additional volumes are referred to, but the 
entries in their catalog recovery areas are not exported. The 
EXPORTRA command parameters are: 


OUTFILE, which is required and identifies the non-VSAM data 
set that is to receive the exported information. 


CRA, which is required and identifies the catalog recovery 
area and volumes from which the export is to take place. 
YLVO identifies the DD statement of the recovery volume. 
The ENTRIES subparameter identifies the three entries which 
are to be copied. 


LARGE. DATASET.A requires the VOLA subparameter because the 
VSAM data set is contained on three volumes. Similarly, 
LARGE.DATASET.B requires the VOLB subparameter. However, 
LARGE. DATASET.C is contained wholly within the catalog 
recovery volume, and, therefore, does not require an 
additional ddname3 subparameter. 


The VLV1 NONE and VLV2 NONE subparameters are necessary, 
because the volumes they identify are referenced in previous 
ddname3 subparameters CVOLA and VOLB); however, the contents 
of their catalog recovery areas are not to be copied. 


FORCE, which specifies that timestamp mismatches are to be 
lgnored. : 
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IMPORT CONNECT 


The IMPORT CONNECT command connects a user catalog. The format 
of this command is: 


IMPORT CONNECT 
OBJECTS ( (Cusercatname 
DEVICETYPE(devtype) 


- VOLUMES(volser))) 
[CATALOG(mastercatnamel /password])] 





IMPORT CONNECT PARAMETERS 


Required Parameters 


CONNECT 
specifies that a user catalog is to be connected. The user 
catalog is connected to the master catalog in the receiving 
system. When CONNECT is coded, OBJECTS must also be coded 
to name the catalog and to identify the volume serial 
pera and device type of the volume that contains the user 
catalog. 


Abbreviation: CON 


OBJECTS( Cusercatname 
DEVICETYPE(devtype) 
VOLUMES volser))) 
specifies the user catalog to be connected. 


specifies the name of the user catalog being 
connected. 


DEVICETYPE(devtype) 
specifies the device type of the volume that contains 
a user catalog that is to be connected. You can 
specify a device type for any direct access device 
that 1s supported. 


Abbreviation: DEVT 


VOLUMES (volser) 
specifies the volume on which the user Sataios 
resides. 


VOLUMES is required when a user catalog is to be 
import connected. VSAM user catalogs may only be on 
one volume so only one volume should be specified when 
connecting a VSAM user catalog. 


Optional Parameters 
CATALOG(catnamel/ 


) 
specifies the name of the catalog in which the catalog you 
are connecting is to be defined. This parameter is 
required when the catalog is password-protected or when you 
want to direct the catalog's entry to a particular catalog 
other than the master catalog. 


is the name of the catalog in which the catalog you 
are connecting is to be defined. If the specified 
catalog is not the master catalog, the catalog must be 
identified by a JOBCAT or STEPCAT DD statement. If 
you are import connecting a user catalog, the 

| specified catalog is usually the master catalog. 
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specifies the master catalog's update- or higher-level 
password. RACF: The update or higher RACF authority 
to the master catalog is required. 


Abbreviation: CAT 
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IMPORT CONNECT 
IMPORT CONNECT EXAMPLE 


Importing to Connect a User Catalog: Example 1 


In this example, a user catalog, D27UCAT1, is connected to the 
system's master catalog, AMAST1. This example reconnects the 
user catalog, D27UCAT1, that was disconnected in the EXPORT 
DISCONNECT example. 


//TMPORT1 JOB... 
//STEPI EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
S/SYSIN DD x 


IMPORT ~- 
OBJECTS - 
CD27UCAT1 - 
! VOLUMECVSERO2) - 
| nee = 
CONNECT - 


CATALOGCAMAST1/MASTMPW1I) 
7% 


The IMPORT command builds a user catalog connector entry that 
identifies the user catalog D27UCAT1 in the master catalog 
AMAST1. Its parameters are: 


° OBJECTS, which is required when a user catalog is being 
imported. The subparameters of OBJECTS identify the user 
catalog, D27UCAT1; the user catalog's volume, VSER02; and 
the device type of the user catalog's volume, 53380. 


e CONNECT, which specifies that the user catalog connector 
entry is to be built and put in the master catalog to 
connect the user catalog to the master catalog. CONNECT is 
required when a user catalog is being reconnected. 


e CATALOG, which identifies the master catalog, AMAST1, and 
specifies its update- or higher-level password, MASTMPH1. 
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IMPORT PARAMETERS 


Required Parameters 


on 


IMPORT 


The IMPORT command restores a VSAM cluster or alternate index 
from a portable data set created by the EXPORT command. The 
format of this command is: 


IMPORT 


EINFILE (ddname} | INDATASET Centryname)} 
COUTFILE(ddnamel /password] ) 

OUTDATASET (entrynamel “password! )} 
[ERASE |NOERASE] 
CLINTOEMPTY] 
mir pei 


[FILE( ddname)] 
[(KEYRANGES(Clowkey highkey) 
[(Clowkey highkey 


ewe dda 
[ NEWNAME ( ame)] 
[ORDERED | UNORDERED] 
[VOLUMES(volserf volser...1)]) 
[Centryname...)J...1)] 
[ PURGE | NOPURGE] 
[SAVRAC | NOSAVRAC ] 


[CATALOG( catnamel /password] )]1 





IMPORT may be abbreviated: IMP. 


INFILE( ddname) | INDATASETlentryname) 
specifies the name of a DD statement or names the portable 
data set that contains a copy of the cluster or alternate 
index to be imported. 


INFILE( ddname) 


specifies the name of a DD statement that identifies 
the portable copy of the cluster or alternate index to 
be imported. 


If a nonlabeled tape or a direct access data set 
created by DOS/VS access method services contains the 
copy, the following DCB parameters must be specified 
on the referenced DD statement: 


e BLKSIZE. If you specified BLKSIZE when the 
cluster or alternate index was exported, you must 
specify the same block size value for IMPORT. If 
you did not specify a block size for EXPORT, a 
default value of 2048 was used. Consequently, if 
you do not specify BLKSIZE for IMPORT, IMPORT sets 
the block size to 2048. 


° LRECL. LRECL is based on the maximum record size 
of the exported VSAM data set. Maximum record 
Size is determined by the value specified via the 
maximum subparameter of the RECORDSIZE parameter 
of the DEFINE CLUSTER or DEFINE ALTERNATEINDEX 
command when the data set was defined. 


° RECFM. Must be VBS. 
Abbreviation: IFILE 


INDATASETCentrvyname ) 


specifies the name of the portable data set that 
contains a copy of the cluster or alternate index to 
be imported. 
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If INDATASET is specified, the portable data set is 
dynamically allocated. The entryname must be 
cataloged in a catalog that is accessible by the 
system into which the entry is to be imported. 


Abbreviation: IDS 
OUTFILE( ddnamel /password1) | OUTDATASET(entrynamel /password]) 


specifies the name of a DD statement or the name of a 
cluster or alternate index to be imported. 


When you use OUTFILE or OUTDATASET to describe the data 
set, you must identify the data set's catalog with a JOBCAT 
or STEPCAT DD statement unless: 


e The data set's entry is in the master catalog, or 


® The first qualifier of the data set's qualified name is 
the catalog's name or alias. 


Notes: 


1. When importing a cluster that was permanently exported, 
the OUTFILE parameter should be used. 


2. If a concatenated JOBCAT or STEPCAT DD statement is 
used, the catalog to be imported must be identified in 
the first DD statement, unless the catalog is specified 
with the CATALOG parameter. 


OUTFILE(ddnamel/password]) 
specifies the name of a DD statement that identifies 
the data set name and volume(s) of the cluster or 
alternate index to be imported. 


If the object was permanently exported and/or you are 
importing to a volume other than the original volume, 
the DD statement specifies the name of the cluster or 
alternate index as DSNAME, the volume serial 

number(s), the device type, DISP=OLD, and AMP="AMORG'*. 


If the object has its data and index components on 
different device types, do not specify OUTFILE——use 
OUTDATASET. 


If NEWNAME is specified for the cluster or alternate 
index entry, the data set name on the DD statement 
must be the same as the new name. The volume that is 
to receive the imported cluster or alternate index 
must be owned by a VSAM catalog. Also, this should be 
the same name declared on the NEWNAME parameter. 
Failure to do so will result in the deletion of the 
original cluster. 


is the update- or higher-level password of the 
target object. You must supply the password when 
the target data set is empty. (See the VOLUMES 
parameter for more information about importing 
into an empty data set.) Otherwise, IMPORT 
obtains the required VSAM data set passwords from 
the portable data set. RACF: The update or 
higher RACF authority to the target object is 
required. 


Abbreviation: 
OUTDATASET Centryvnamel/ 


specifies the name of the cluster or alternate index 
that is to be imported. When you specify OUTDATASET, 
the VSAM data set you identify is dynamically 
allocated. | 
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You may use concatenated DD statements if the object 
was permanently exported and its data and index 
components are on different device types. The first 
DD statement specifies the name of the cluster or 
alternate index as the DSNAME, the volume serial 
numbers and device type of the data component, 
DISP=OLD, and AMP="AMORG'. The second DD statement 
specifies the name of the index component as the 
DSNAME, the volume serial numbers and device type of 
the index component, DISP=OLD, and AMP="AMORG'’. 


If NEWNAME is specified for the cluster or alternate 
index entry, entryname must be the same as the new 
name. Also, this should be the same name declared on 
the NEWNNAME parameter. Failure to do so will result 
in the deletion of the original cluster. 





is the update- or higher-level password of the 
target object. (See password under OUTFILE for 
password requirements of the target data set.) 
RACF: The update or higher RACF authority to the 
target object is required. 


Abbreviation: ODS 


Optional Parameters 
CATALOG( catnamel[/password] ) 


specifies the name of the catalog in which the imported 
object is to be cataloged. This parameter is required when 
the catalog is password-protected. 


come specifies the name of the catalog in which the entry 
( to be imported is to be defined. 


specifies the catalog's update- or higher-level 
password. RACF: The update or higher RACF authority 
to the catalog is required. When you import an 
alternate index whose base cluster 1s 
password-protected, you should supply the catalog's 
master password. RACF: The alter RACF authority to 
the catalog 1s required. Otherwise, you Cor the 
operator) will be prompted to supply the base 
cluster's master password. RACF: The alter RACF 
authority to the base cluster is required. When you 
import an integrated catalog facility user catalog and 
INTOEMPTY is not specified, the master password of the 
master catalog is required. RACF: The alter RACF 
authority to the master catalog is required. 


Abbreviation: CAT 


ERASE | NOERASE 
specifies whether the data component of the cluster or 
alternate index is to be erased (that is, overwritten with 
binary zeros). This parameter can be used only when you 
are importing the object into the system from which it was 
previously exported with the TEMPORARY option. This 
parameter overrides whatever was specified when the object 
was defined or last altered. 


ERASE 
specifies that the data component is to be overwritten 
‘with binary zeros when the cluster or alternate index 
is deleted. If ERASE is specified, the volume that 
C contains the data component must be mounted. 
~%. 


Abbreviation: ERAS 
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NOERASE 


specifies that the data component is not to be 
overwritten with binary zeros when the cluster or 


alternate index is deleted. 
Abbreviation: NERAS 
INTOEMPTY 


specifies that you are importing from the portable data set 
into an empty data set. If this parameter is not 
specified, an attempt to import into an empty data set will 


fail. The password and RACF profiles associated with the 


empty data set will be retained. 


When importing into an empty data set, the SAVRAC|NOSAVRAC 
parameter applies only to the paths imported and 
successfully defined over the empty data set. 


define of an exported path fails because a catalog entry 


with the same name already exists, the path on the portable 


data set is ignored. 
Abbreviation: IEMPTY 
OBJECTS 
ee 
FILE( 


ddname)] 
{KEVRANGES! (Loukey highkey){(lowkey highkey)...})} 


CNEWNAME (newname)] 
[ORDERED | UNORDERED] 
[VOLUMES(volserl volser...1)]) 
[Centryname...)...J)] 


specifies the new or changed attributes for. the cluster, 
alternate index, or any associated paths to be imported. 


Access method services matches each entryname you specify 
through the OBJECTS parameter against the name of each 


object on the portable data set. When a match is found, ie 
the information specified by OBJECTS overrides the NG 
information on the portable data set. Seat 


specifies the name of the data component, index 
component, cluster, alternate index, or path for which 
attributes are being specified. The entryname must 
appear on the portable data set; otherwise, the 
parameter list will be ignored. 


Abbreviation: OBJ 
FILE(ddname) 


specifies the name of a DD statement that identifies 
the volumes allocated to the data and index components 
of a key~sequenced cluster or an alternate index. 


This parameter is used when the components are defined 
aS unique and when the data and index components 
reside on different device types. FILE can be coded 
twice within the OBJECTS parameter: once in the 
parameter set for the index component and once ina 
second parameter set for the data component. 


If you do not specify FILE, the required volumes are 
dynamically allocated. The volumes must be mounted as 
permanently resident and reserved. 


KEYRANGES((Clowkey highkevy)[(lowkey highkey)...])} 
specifies portions of a key~sequenced cluster or 
alternate index to be placed on separate volumes. 


The data is divided, by key, among the volumes as 
contained in the portable data set or as specified in 
the VOLUMES parameter. 
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If a volume serial number is duplicated on the 
portable data set or in VOLUMES, multiple key ranges 
of an alternate index or cluster attribute are placed 
on that volume. 


If the number of volumes is greater than the number of 
key ranges, the excess volumes are used for overflow 
records from any key range without consideration of 
range boundaries. If there are fewer volumes than key 
ranges, the excess key ranges are placed on the last 
volume specified. 


By using the KEYRANGE parameter, you may specify Key 
range pairs for a key-~sequenced data set that 
previously was not divided by Key or that was divided 
in different Key range groups. 


The maximum number of Key range pairs is 20. Key 
ranges must be in ascending order, and may not 
overlap. Gaps may exist within a specified set of 
ranges, but records cannot be inserted within a gap. 


When you specify KEYRANGES, the entryname can be 
either the cluster or alternate index name or the name 
of the data component. If you specify KEYRANGES with 
the cluster or alternate index name, the values 
specified are defined for the data component. If you 
specify KEYRANGES with the data component name, the 
values are defined for the data component, and any 
specification of KEYRANGES with the cluster or 
alternate index name is overridden. 


Keys can contain 1 to 64 characters; if coded in 
hexadecimal, they can contain 1 to 128 hexadecimal 
characters. All EBCDIC characters are allowed. 


specifies the low key of the key range. If 
lowkey is shorter than the actual keys, it will 
be padded with binary zeros. 


highkey 
specifies the high key of the key range. If 
highkey is shorter than the actual keys, it will 
be padded with binary ones. 


Abbreviation: KRNG 


NEWNAME (newname ) 


specifies the new name of an imported cluster or 
alternate index or its components, or an associated 
path. When you specify NEWNAME, only the name 
specified as entryname is changed. 


If you are specifying a new name for a cluster or 
alternate index that was exported with the TEMPORARY 
option and it is being imported back into the original 
system, you must also rename each of its components. 


Abbreviation: NEWNM 


ORDERED | UNORDERED 


specifies whether volumes are to be used in the order 
in which they were listed when the data set was 
originally defined Cas contained on the portable data 
set) or in the VOLUMES parameter. 


If the data set is divided into key ranges, all the 
records within the range specified by the first 
low-key high-key pair are placed on the first volume; 
all the records within the second range are placed on 
the second volume, and so on. 
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If it is impossible to allocate volumes in the given 
order and ORDERED is specified, the command is 
terminated. 


When you specify ORDERED|UNORDERED, you can specify 
the cluster or alternate index name, the data 
component name or the index component name as 
entryname with the following results: 


If ORDERED|UNORDERED is specified with the cluster 


or alternate index name, the specified attribute 


is defined for the data component. For a 
key-sequenced cluster or alternate index, the 
specified attribute is also defined for the index 
component. 


If ORDERED|UNORDERED is specified with the data 
component name, the specified attribute is defined 
for the data component. Any specification of 
ORDERED| UNORDERED with the cluster or alternate 
index name is overridden. 


For a key~sequenced cluster and for an alternate 
index, if ORDERED|UNORDERED is specified with the 
index component name, the specified eee is 
defined for the index component. An 

specification of ORDERED] UNORDERED with the 
cluster or alternate index name is overridden. 


If OBJECTS is specified and neither ORDERED or 
UNORDERED is specified, then UNORDERED is the default. 


Abbreviations: ORD and UNORD 


VOLUMES(volserf volser...]) 
specifies the volumes on which the cluster or 
alternate index is to reside. 


If VOLUMES is not coded, the original volume is the 
receiving volume. 


If the portable data set was created with an EXPORT 
command using the PERMANENT option on a Release 1 
version of access method services (DOS/VS Release 29, 
OS/VS1 Release 2, OS/VS2 Release 1.6, or OS/VS2 
Release 2), this parameter is required. Portable data 
sets created by Release 1] using the PERMANENT option 
do not contain volume information. 


When you specify VOLUMES, you can specify the cluster 
or alternate index name, the data component name or 
the index component name as entryname with the 
following results: 


If VOLUMES is specified with the cluster or 
alternate index name, the specified volume list is 
defined for the data component. For a 
key-~sequenced cluster or alternate index, the 
specified volume list is also defined for the 
index component. 


If VOLUMES is specified with the data component 

name, the specified volume list is defined for the 
data component. Any specification of VOLUMES with 
the cluster or alternate index name is overridden. 


For a key~sequenced cluster or alternate index, if 
VOLUMES is specified with the index component 
name, the specified volume list is defined for the 


index component. Any specification of VOLUMES 


with the cluster or alternate index name is 
overridden. 
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For clusters or alternate indexes, if multiple volumes 
are specified, they must be of the same device type. 
By repeating the OBJECTS parameter set for each 
component and including VOLUMES in each parameter set, 
you can have the data and index components on 
different volumes. Although the index and data 
components may reside on different device types, each 
oe of a multivolume component must be of the same 
ype. 


If the receiving volume is of a type different from 
that which originally contained the cluster or 
alternate index, the job may be terminated because of 
allocation problems. Each space allocation quantity 
is recorded in a catalog entry as an amount of 
cylinders or tracks even if RECORDS was specified in 
the DEFINE command. 


When a cluster or alternate index is imported, the 
number of cylinders or tracks in the catalog entry is 
not modified, even though the object may be imported 
to reside on a device type other than what it was 
exported from. If an object is exported from a 
smaller DASD and imported to a larger DASD, more space 
is allocated than the object needs. Conversely, if an 
attempt is made to import an object that previously 
Jot tea on a larger DASD to a smaller DASD, it may 
ail. 


You can avoid space allocation problems by defining an 
empty cluster or alternate index and identifying it as 
the target for the object being imported as described 
below: 


® Using the DEFINE command, define a new entry for 
the cluster or alternate index in the catalog to 
which it is to be moved. If space was allocated 
in RECORDS, you may specify the same quantity; if 
it was allocated in TRACKS or CYLINDERS, you must 
adjust the quantity for the new device type. If 
an entry already exists in the catalog for the 
object, you must delete that entry or use a 
different name in the DEFINE command. 


@ Using the IMPORT command, load the portable data 
set into the newly defined cluster or alternate 
index. When IMPORT encounters an empty target 
data set, the exported catalog information is 
bypassed and only the data records are processed. 


Abbreviation: VOL 


PURGE | NOPURGE 


specifies whether the original cluster or alternate index 
is to be deleted and replaced, regardless of the retention 
time specified in the TO or FOR parameter. This parameter 
can be used only when you are importing the object into the 
original system from which it was exported with the 
TEMPORARY option. 


PURGE 
specifies that the object is to be deleted even if the 
retention period has not expired. 
Abbreviation: PRG 

NOPURGE 
specifies that the object is not to be deleted unless 
the retention period has expired. 


Abbreviation: NPRG 
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SAVRAC | NOSAVRAC 


specifies, for a RACF-protected object, whether existing 
profiles are to be used or whether new profiles are to be 
created. | rae 


SAVRAC 
specifies that RACF data set profiles already existing 
for objects being imported from the portable data set 
are to be used. Typically, you would specify this 
option when replacing a data set with a portable copy 
made with an EXPORT TEMPORARY operation. SAVRAC will 
cause the existing profiles to be saved and used; 
rather than letting the system delete old profiles and 
create new, default profiles. 


The profiles will actually be redefined by extracting 
information from existing profiles and adding caller 
attributes. You should ensure that these added 
attributes are acceptable. 


The ownership creation group and access list will be 
altered by the caller of the SAVRAC option. 


Caution: You should ensure that valid profiles do 
exist for clusters being imported when SAVRAC is 
specified. If this is not done, an invalid and 
possibly improper profile may be "saved" and used 
inappropriately. 


NOSAVRAC 
specifies that new RACF data set profiles are to be 
created. This is usually the situation when importing 
a permanently exported cluster. 


A profile will be defined for the imported cluster if 
either the automatic data set protection option has 

been specified for you or if the exported cluster had 
a RACF indication in the catalog when it was exported. 


If you import into a catalog in which there is a 
component with a duplicate name that is marked as 
having been temporarily exported, it and any 
associated profiles will be deleted before the 
portable data set is imported. 
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IMPORT EXAMPLES 


Importing a Key-Sequenced Cluster: Example 1 


In this example, a key-sequenced cluster, D40.EXAMPLE.KSDSI1, 

that was speviodsly: exported, is imported. (See the previous 
EXPORT example, "Exporting a Key~Sequenced Cluster.™) OUTFILE 
i A ec DD statement are provided to allocate the 

ata set. 


The original copy of D40.EXAMPLE.KSDS1 is replaced with the 
imported copy, TAPE2. Access method services finds and deletes 
the duplicate name, DG0.EXAMPLE.KSDS1, in the catalog D27UCAT1. 
CA duplicate name exists, because TEMPORARY was specified when 
the cluster was exported.) Access method services then 
redefines DG0O.EXAMPLE. Se using the catalog information from 
the portable file, TAPE2 


//IMPORT2 JOB ; 
//STEPI EXEC PGM=IDCAMS 
// SOURCE DD DSNAME=TAPE2, UNIT=CTAPE, , DEFER), 
7 VOL=SER=003030,DISP=OLD, 
4/7 DCB=CBLKSIZE=6000, LRECL=479, DEN=3),LABEL=(1,SL) 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD % 
IMPORT - 
INFILECSOURCE) - 
OUTDATASETCD40.EXAMPLE.KSDS1) - 
CATALOGCD27UCAT1/USERMRPW) 
1% 


Job control language statement: 


e SOURCE DD, which describes the portable data set, TAPE2. 
TAPE2 resides on a magnetic tape file that will not be 
mounted by the operator until access method services opens 
TAPE2 for processing. The block size parameter is included 
Ceven though it need not be, because the tape has a standard 
label and the information is contained in the data set 
header label) to illustrate the fact that the information 
specified when the data set is imported is required to be 
the same as was specified when the data set was exported. 
The LRECL parameter is not required, because the maximum 
record size is 475 bytes and the default (block size minus 
G4) is adequate. However, by specifying a record size, the 
default is overridden and virtual storage is more 
efficiently used. To specify a record size, specify the 
Size of the largest record plus 4. 


The IMPORT command copies the portable data set, TAPE2, into the 
system and assigns it the name D4G0.EXAMPLE.KSDS1. When TAPE2 is 
copied, access method services reorganizes the data records so 
that deleted records are removed and control intervals and 
control areas contain the specified free space percentages. The 
original copy of the cluster is deleted and replaced with the 
data records from the TAPE2 portable file. The IMPORT command's 
parameters are: 


° INFILE, which points to the SOURCE DD statement. The SOURCE 
DD sober describes the portable file, TAPE2, to be 
imported. 


e OUTDATASET, which gives the name of the data set being 
imported. Because the high-level qualifier of the data set 
is the name of the alias of the user catalog D27UCAT2, 
access method services can dynamically allocate the cluster 
without specifying a JOBCAT or STEPCAT DD statement. 


* CATALOG, which identifies the catalog, D27UCAT1, in which 


the imported cluster is to be defined. The catalog's 
update- or higher-level password is required. 
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Importing an Entry-Sequenced Cluster in a VSAM Catalog: Example 2 


In this example, an entry-~sequenced cluster, D50.EXAMPLE.ESDSI, 
is imported from a portable file, TAPE]. This example is 
associated with EXPORT example, "Exporting an Entry-Sequenced 
Cluster." The cluster is defined in a different catalog than 
that from which it was exported, assigned a new name, and 
imported to a different volume. 


//IMPORT3 JOB. 

//STEP1 EXEC PGM= IDCAMS 

//SOQURCE DD DSNAME=TAPE1,UNIT=CTAPE,, DEFER), DISP=OLD, 
Sf VOL=SER=001147,LABEL=(1,SL) 

//SYSPRINT DD SYSOUT=A 

/7SYSIN DD x% 


INFILECSOURCE) - 
OUTDATASETCD40.EXAMPLE.ESDS3) - 
OBJECTSC( —- 
(D50.EXAMPLE.ESDS1 - 
NEWNAMECDG0.EXAMPLE.ESDS3) —- 
VOLUMESCVSERO2) ) - 


) 
CATALOGCD27UCATI/USERUPPW) 
7% 


Job control language statement: 


e SOURCE DD, which describes the portable file, TAPE1L. TAPEI1 
resides on a magnetic tape file that will not be mounted by 
the operator until access method services opens TAPE1 for 
processing. 


The IMPORT command moves the contents of the portable file, 

TAPE], into the system. When TAPE] is moved, access method 

services reorganizes the data records. The IMPORT command's 
parameters are: 


° INFILE, which points to the SOURCE DD statement. The SOURCE 
DD statement describes the data set to be imported, TAPE1. 


e OUTDATASET gives the name of the data set that is being 
imported; the name is the renamed cluster. Because the 
high-level qualifier of the data set name is the name of the 
alias of the catalog, D27UCAT1, the data set can be 
dynamically allocated without specifying a JOBCAT or STEPCAT 
DD statement. 


e OBJECTS, which changes some of the attributes for the object 
being imported: 


_ D50.EXAMPLE.ESDS1, which identifies the entry-~sequenced 
cluster as it is currently named on TAPEI1. 


_ NEWNAME, which specifies that the cluster's entryname is 
to be changed to DG0O.EXAMPLE.ESDS3. 


- VOLUMES, which identifies the new volume on which the 
cluster is to reside. 


e CATALOG, which identifies the catalog, D27UCATI1, that is to 
contain the cluster's catalog entry. The catalog's update- 
or higher-level password is required. 
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IMPORTRA 


The IMPORTRA command restores catalog entries from a portable 
data ace created by the EXPORTRA command. This command is for 
use with recoverable catalogs only. 


The format of the IMPORTRA command is: 


IMPORTRA| {INFILE(ddname) | INDATASET (Centryname J} 


[OUTFILE(ddname)1] 
Bae et 


entryname 
CDEVICETYPES (dev tvpel devtype...1)] 


C[FILE(ddname)] 


(VOLUMES (yolserl | yolser...1}1) 
Reece seve 


CCentryname 
[SAVRAC | NOSAVRAC] 
[CATALOG( catnamel[/password])1 





IMPORTRA can be abbreviated: MPRA. 


IMPORTRA PARAMETERS 


Required Parameters 


INFILE(ddname) 
names the DD statement that describes the portable data set 
(the data set that resulted when you issued the EXPORTRA 
command). If the portable data set resides on a nonlabeled 
tape or ina direct access data set created by DOS/VS 
access method services, the DCB BLKSIZE parameter must be 
specified on the referenced DD statement. 


If you specified BLKSIZE for the portable data set that was 
created when you executed your EXPORTRA job, you must 
specify the same block size for your IMPORTRA job. (Note: 
If you did not specify a block size for EXPORTRA, a default 
value of 2048 was used. Consequently, if you do not 
specify BLKSIZE for IMPORTRA, IMPORTRA sets the block size 
to 2048.) All other characteristics of the portable data 
set are established by IMPORTRA. 


Abbreviation: IFILE 


INDATASET (Centrvname) 
specifies the data set name of the portable data set (the 
data set that resulted when you issued the EXPORTRA 
command). When you specify INDATASET instead of INFILE, 
the portable data set is dynamically allocated. 


Abbreviation: IDS 


Optional Parameters 


CATALOG( catnamel /password]) 
identifies the target catalog. 


If you do not include the CATALOG parameter, the JOBCAT or 
STEPCAT catalogs are used. If you have not specified a 
JOBCAT or STEPCAT catalog, the VSAM master catalog is used. 
If you don't specify the CATALOG parameter when the target 
catalog is password-protected, the system operator will be 
prompted to supply the correct password. 
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names the catalog. When you specify a user catalog, 
you must describe and allocate the catalog with a 
JOBCAT or STEPCAT DD statement. 


fe) : 
is the target catalog's update- or higher-level 
password, if the catalog is password protected. If 
any of the data sets being imported is an alternate 
index whose base cluster is password-protected, you 
should supply the catalog's master password. RACF: 
The update or higher RACF authority to the catalog is 


required. 
Abbreviation: CAT 
OBJECTS ( 
PDEWICETYPES (dev typel devtype...1)] 


[F ddnane) 
[VOLUMES(yvolser[ volser...1)]) 
[Centryname...)...1) 
The OBJECTS parameter group specifies new or changed 
attributes for objects on the portable data set. 


OBJECTS 
specifies new or changed attributes for a cluster, an 
alternate index, or a non-VSAM data set that is being 
imported. By specifying the OBJECTS parameter, you 
may override certain attributes contained on the 
portable data set. 


Access method services matches each entryname you 
specify against the name of each object on the 
portable data set. When a match is found, the 
information specified by OBJECTS overrides the 
information on the portable data set. 


Abbreviation: OBJ 


specifies the object's entryname. You can 
specify the entryname and associated attributes 
for up to 255 objects. 


You can specify the entryname of these types of 
objects only: VSAM cluster or an alternate 
index, non-VSAM data set, user catalog, and a 
VSAM object's data or index component. 


DEVICETYPES(devtypel devtype...1) 
specifies the device type on which a user catalog 
being imported resides or the device type(€s) on which 
a non-VSAM data set being imported resides. 


If entryname names a user catalog, you may specify 
only one device type. If entryname names a non-VSAM 
data set that resides on different device types, the 
device types listed in the DEVICETYPES parameter must 
be specified in the same order as the volume serial 
numbers listed in the VOLUMES parameter. 


This parameter can be specified only when the 
entryname names a non-VSAM data set or user catalog. 
For a non- VSAM data set or user catalog, if 
DEVICETYPES is not coded, the data set or user catalog 
must still reside on the same device type(s) as 
contained in the entry in the portable data set. 


Abbreviation: DEVT 
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FILE(ddname) 


specifies the name of a DD statement that identifies 
the volumes allocated to the data and index components 
of a key~sequenced cluster or an alternate index. 


This parameter 1s required when the components are 
defined as unique and when the data and index 
components reside on different device types. 


When components reside on different device types, FILE 
must be coded twice within the OBJECTS parameter; once 
in the parameter set for the index component and once 
in a second parameter set for the data component. If 
you do not specify FILE, the required volumes are 
dynamically allocated. 


VOLUMES(volser[ volser...]) 
specifies the volume(s) on which a cluster or 
alternate index is to reside, the volume on which a 
user catalog resides, or the volume(€s) on which a 
non-VSAM data set resides. If entryname names a user 
catalog, you may specify only one volume serial number 
as a subparameter of VOLUMES. 


For a cluster or an alternate index, if VOLUMES is not 
coded, the original volume is the receiving volume. 
For a user catalog or a non-VSAM data set, if VOLUMES 
is not coded, the data set or user catalog must still 
Farts a the same volume(€s) as it did in the portable 
ata set. 


When you specify VOLUMES for a cluster or alternate 
index, you can specify the cluster or alternate index 
name, the data component name or the index component 
name as entryname with the following results: 


° If VOLUMES is specified with the cluster or 
alternate index name, the specified volume list is 
defined for the data component. For a 
key~sequenced cluster or alternate index, the 
specified volume list is also defined for the 
index component. 


e If VOLUMES is specified with the data component 
name, the specified volume list is defined for the 
data component. Any specification of VOLUMES with 
the cluster or alternate index name is overridden. 


e For a key~sequenced cluster or alternate index, if 
VOLUMES is specified with the index component 
name, the specified volume list is defined for the 
index component. Any specification of VOLUMES 
with the cluster or alternate index name is 
overridden. 


For clusters or alternate indexes, if multiple volumes 
are specified, they must be of the same device type. 
By repeating the OBJECTS parameter set for each 
component and including VOLUMES in each parameter set, 
you can have the data and index components on 
different volumes. (See also the description of the 
FILE parameter. ) 


Although the index and data components may reside on 
different device types, each volume of a multivolume 
component must be of the same type. 


Abbreviation: VOL 


OUTFILE(ddname) 


names the DD statement that contains a data set name and 
the volume serial number of each volume that is to contain 
the imported VSAM clusters and alternate indexes. You must 
use concatenated DD statements if the data sets are on 
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different device types. If the OUTFILE parameter is not 
id caer the required data sets are dynamically allocated 
as needed. 





The dsname specified with the DD statement cannot be one of 
the names cataloged in the target catalog (that is, the 
catalog that is to contain the imported catalog entries) 
ane it es be one of the entrynames within the portable 
ata set. 


Catalog Administration Guide describes how this dsname is 
used by IMPORTRA processing. The DD statement(s) also 
specify the volume serial number(s), device type, DISP=OLD, 
and AMP="AMORG'. 


Abbreviation: OFILE 
SAVRAC | NOSAVRAC 


specifies, for a RACF-protected object, whether existing 
profiles are to be used or whether new profiles are to be 
created. 


SAVRAC|NOSAVRAC applies to all VSAM components being 
imported back into the system. 


SAVRAC 
specifies that existing RACF data set profiles are to 
be saved and used, rather than letting the system 
delete old profiles and create new default profiles. 
The profiles will actually be redefined by extracting 
information from existing profiles and adding caller 
attributes. You should ensure that these added 
attributes are acceptable. SAVRAC should be specified 
when RACF data set profiles already exist for objects 
being imported from the portable data set. 


The ownership creation group and access list will be 
altered by the caller of the SAVRAC option. 


Caution: You should ensure that valid profiles do 
exist for all components (for example, cluster, data, 
index) being imported when SAVRAC is specified. If 
this is not done, an invalid and possibly improper 
profile may be saved and used inappropriately. 


Remember that paths are imported with their 
corresponding cluster or alternate index, and the same 
caution applies to these entries. In particular, keep 
in mind that additional paths may be brought in during 
the import. 


NOSAVRAC 
specifies that a profile will be defined for the 
imported components if either the RACF Automatic Data 
Set Protection option has been specified for you or if 
the exported component had a RACF indication in the 
catalog at the time it was exported. NOSAVRAC should 
be specified when you wish new profiles to be created. 


There may be situations in which neither the SAVRAC nor 
NOSAVRAC mode would be suitable for all entities restored 
from the catalog recovery area. In such cases, the 
following procedure is suggested: 


° Issue two separate EXPORTRA commands, resulting in two 
portable data sets. One EXPORTRA will create a 
portable data set containing entities to which SAVRAC 
should apply, the other to which NOSAVRAC should apply. 


e Issue two IMPORTRA commands, one specifying SAVRAC and 
the other NOSAVRAC. 
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IMPORTRA EXAMPLE 


This example shows how EXPORTRA and IMPORTRA can be used to 
recover a VSAM catalog. The first part illustrates the use of 
EXPORTRA. The second part shows how IMPORTRA is used. 


Recovering a VSAM Catalog: Example 1l-~Part 1 (EXPORTRA) 


This example performs the EXPORTRA function against the VSAM 
master catalog, AMASTCAT, and against all the volumes owned by 
it. All the data sets listed in the catalog recovery areas on 
the catalog volume and on the other volumes owned by AMASTCAT 
are exported to a SAM data set on another disk volume. Using 
the FORCE option causes EXPORTRA to ignore time stamp mismatches 
between the volumes and the catalog. 


/7RECOVER JOB gras 

//STEPI EXEC PGM=IDCAMS 

“/SYSPRINT DD SYSOUT=A 

//CRAVOLI1 DD DISP=OLD,VOL=SER=VSERO1,UNIT=DISK, 


// AMP=*AMORG' 
//CRAVOL2 DD DISP=OLD, VOL=SER=VSERO4,UNIT=DISK, 
17 AMP="AMORG' 
//PORT DD DSNAME=PORT, DISP=CNEW, KEEP), 
// SPACE=C(CYL, (€3,3)),VOL=SER=231401, 
// UNIT=DISK, DCB=BLKSIZE=8000 
S/SYSIN DD X 
EXPORTRA - 
CRAC - 
CCRAVOLI ALL) - 
eee ALL) - 
FORCE - 
OUTFILECPORT) - 
MASTERPNCMCATMRPW) 


7% 


Job control language statements: 


e CRAVOL1 DD, which identifies and allocates the first volume 
whose catalog recovery area contents is to be exported. 


e CRAVOL2 DD, which identifies and allocates the second volume 
whose catalog recovery area contents is to be exported. 


e PORT DD, which identifies the sequential file that is to 
receive the exported data sets and catalog recovery records. 
The DCB BLKSIZE parameter overrides the EXPORTRA default of 
2048 to improve performance. 


The EXPORTRA command exports everything appearing in the catalog 
recovery areas of volumes VSERO1 and VSEROG. The EXPORTRA 
command's parameters are: 


e CRA, which is required and identifies the catalog recovery 
areas and volumes from which the export is to take place. 
The ddnames of the DD statements for these objects must be 
identical to the names specified for this parameter. The 
ALL subparameter specifies that everything is to be exported 
from each catalog recovery area. 


e FORCE, which specifies that timestamp mismatches are to be 
ignored. 


® OUTFILE, which is required and identifies the sequential 
CSAM) non-VSAM data set that is to receive the exported 
information. The ddname of the DD statement for this object 
must be identical to the name specified with this parameter. 


e MASTERPW, which specifies the master password of the master 
catalog. This parameter is required in order to export 
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information from catalog recovery areas controlled by a 
recoverable catalog. 


Recovering a VSAM Catalog: Example 1--Part 2 CIMPORTRA) 


This example imports all the data sets that were exported using 
EXPORTRA in the previous example. The receiving catalog is the 
VSAM master catalog, and the CATALOG parameter is used to supply 
its master password. 


//RESTORE JOB 


//STEP1L EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//PORT DD DSNAME=PORT, DISP=OLD,UNIT=DISK, 
// VOL=SER=333333,DCB= BLKSIZE= 8000 
Z/NSAMIN DD DSNAME=DUMMY .NAME, DISP=OLD,UNIT=DSIK, 
7 VOL=SER=VSERO1,AMP=*AMORG' 
17 DD VOL=SER=VSER04, UNIT=DISK, DISP=OLD 
“/7SYSIN DD xX 
IMPORTRA —- 
INFILECPORT) - 
OUTFILECVSAMIN) - 


CATALOGCAMASTCAT/MCATMRPNW) 
7% 


Job control language statements: 


e PORT DD, which identifies and allocates the portable data 
set created previously by EXPORTRA. The DCB BLKSIZE 
parameter is included Ceven though it need not be, because 
the information is contained in the DSCB for the data set) 
to illustrate the fact that the block size specified in the 
IMPORTRA job must be the same as that specified in the 
EXPORTRA job that created the portable data set. 


® VSAMIN DD, which identifies and allocates the volumes of the 
objects to be imported. This permits them to be reloaded 
from the portable data set. The dsname appearing on the DD 
statement is required. It 1s a dummy name that must not 
appear either in the catalog or among the names on the 
portable data set. Because the volumes are of different 
device types, concatenated DD statements must be used. 


The IMPORTRA command imports the data sets written on the 
portable data set by EXPORTRA previously. The IMPORTRA 
command's parameters are: 


8 INFILE, which is required and which identifies the portable 
data set. 


e OUTFILE, which identifies each VSAM volume involved in the 
import. The DD statement identified by OUTFILE also 
identifies the dummy data set, DUMMY.NAME. 


6 CATALOG, which specifies the name of the master catalog. 
The master password of the target catalog is required in 
order to import catalog information. 
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LISTCAT PARAMETERS 


Required Parameters 


Optional Parameters 





LISTCAT 


The LISTCAT command lists catalog entries. The format of this 
command is: 


LISTCAT [ALIAS] 
LALTERNATEINDEX] 
[CLUSTER] 
CDATA] 
[GENERATIONDATAGROUP] 
[INDEX] 
C[NONVSAM] 
C[PAGESPACE] 
[PATH] 
[SPACE] 
C[USERCATALOG] 
[CREATION( days)1 
[ENTRIESCentry namel/password] 
[ entrynamel/password]...1)}| 
LEVEL( level )] 
ue ee 


HISTORY | 
VOLUME | 
A pala 


ALL 
[NOTUSABLE: ] 
COUTFILE(ddname) 1 


[CATALOG( catnamel /password1])] 





LISTCAT can be abbreviated: LISTC 


The LISTCAT command has no required parameters. 


When the LISTCAT command is issued as a job step (that is, not 
through TSO) and no parameters are specified; an entire catalog 
is listed. See the section "Order of Catalog Search for 
LISTCAT™ on page 18 for a description of how the catalog to be 
listed is selected. 


Note to TSO users: When LISTCAT is invoked from a TSO terminal 
and no operands are specified, the prefix of the TSO user 
becomes the highest level of entryname qualification and only 
those entries with a matching highest level of qualification are 
listed. It is as if you specified: 


LISTCAT LEVEL(TSO user prefix) 


CLALIAS] L[ALTERNATEINDEXI[CLUSTERI[DATAI 

[ GENERATIONDATAGROUP 1 [INDEX] [NONVSAM] 

[PAGESPACEILPATHI [SPACE] [USERCATALOG] 
specifies that certain types of entries are to be listed. 
Only those entries whose type is specified are listed. For 
example, when you specify CLUSTER but not DATA or INDEX, 
the cluster's entry is listed and its associated data and 
index entries are not listed. 


When you specify ENTRIES and also specify an entry type, 


the entryname is not listed unless it is of the specified 
type. You can specify as many entry types as desired. 
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When you want to completely list a catalog, do not specify 


any entry type. om 
| | , / 
-ALTAS 7 | Mo 
specifies that alias entries are to be listed. 
ALTERNATEINDEX 


specifies that entries for alternate indexes are to be 
listed. If ALTERNATEINDEX is specified and DATA and 
INDEX are not also specified, entries for the 

pr a index's data and index components are not 
isted. 


Abbreviation: AIX 


CLUSTER 
specifies that cluster entries are to be listed. If 
CLUSTER is specified and DATA and INDEX are not also 
specified, entries for the cluster's data and index 
components are not listed. 


Abbreviation: CL 


DATA 
specifies that entries for data components of clusters 
and alternate indexes are to be listed. 


If a VSAM object's name is specified and DATA is 
coded, only the object's data component entry is 
listed. When DATA is the only entry type parameter 
coded, the catalog's data component is not listed. 


GENERATIONDATAGROUP 
specifies that entries for generation data groups are 
to be listed. 


Abbreviation: GDG << 


INDEX 
specifies that entries for index components of 
key~sequenced clusters and alternate indexes are to be 
listed. If a VSAM object's name is specified and 
INDEX is coded, only the object's index component 
entry is listed. When INDEX is the only entry type 
arvana coded, the catalog's index component is not 
isted. 


Abbreviation: IX 


NONVSAM 
specifies that entries for non-VSAM data sets are to 
be listed. If a generation data group's name and 
non-VSAM are specified, the generation data sets 
associated with the generation data group are listed. 


Abbreviation: NVSAM 
PAGESPACE 
specifies that entries for page spaces are to be 
listed. 
Abbreviation: PGSPC 


PATH 
specifies that entries for paths are to be listed. 
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SPACE | : 
specifies that entries for volumes containing data 
spaces defined in this catalog are to be listed. 
Candidate volumes are included. If entries are 
identified by entryname, SPACE can be coded only when 
no other entry type parameter is coded. 


Abbreviation: SPC 


USERCATALOG 
specifies that catalog connectors are to be listed. 
The user catalog connector entries are in the master 
catalog. (CUser catalog connector entries can also be 
in a user catalog, but the operating system does not 
recognize them when searching for a user catalog.) 


Abbreviation: UCAT 


CATALOG( catnamel[/password]) 


specifies the name of the catalog that contains the entries 
that are to be listed. If CATALOG is coded, only entries 
from that catalog are listed. See "Order of Catalog Search 
for LISTCAT™ on page 18 for information about the order in 
which catalogs are searched. 


e 
is the name of the catalog. 


password 
specifies the read- or higher-level password of the 
catalog that contains entries to be listed.  RACF: The 
read or higher RACF authority to the catalog is 
required. If the entries to be listed are password 
protected, a password must be supplied either through 
this parameter or through the ENTRIES parameter. 
passwords are to be listed, you must specify the 
master password. RACF: The alter RACF authority to 
the catalog 1s required. 


If the catalog's volume is physically mounted, it is 
dynamically allocated. The volume must be mounted as 
permanently resident or reserved. 


Abbreviation: CAT 


CREATION( days) 


specifies that entries of the indicated type, such as 
CLUSTER and DATA, are to be listed only if they were 
created the specified number of days ago or earlier. 


days 
specifies the number of days ago. This value can be 
expressed in decimal, hexadecimal, or binary. If it 
is expressed in either hexadecimal or binary, it must 
be preceded by either 'X* or 'B! and be enclosed in 
single quotation marks. 


The maximum number that can be specified is 9999; zero 
indicates that all entries are to be listed. 


Abbreviation: CREAT 


ENTRIES(entrynamel/passwordi[ entry namel/password]...1)] 
LEVEL(Clevel ) 








specifies the names of entries to be listed. 


Entries are only listed from an OS CVOL if the ENTRIES or 
LEVELS parameter is specified and: 


6 The CATALOG parameter is not specified. 
¢ No JOBCAT or STEPCAT DD is specified. 
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e The higher-level qualifier of the name specified using 
ENTRIES or LEVELS is the alias of the OS CVOL. 


When a LISTCAT LEVEL of a CVOL is mags: a maximum of 1456 
entries can be listed. 





Note to TSO users: 1TS0 will prefix the userid to the 
specified data set name when the ENTRIES parameter is 
unqualified. The userid is not prefixed when the LEVEL 
parameter is specified. 


ENTRIES {entrynamel /password] 
[entrynamel/password]...]) 

specifies the name or generic name of each entry to be 
listed. (See the generic examples following the 
description of the LEVEL parameter.) When you want to 
list the entries that describe a user catalog, the 
catalog's volume must be physically mounted. You then | 
specify the catalog'sS name as the entryname. If you 
want data space information, you must specify the 
volume serial number Cas the entryname) of the volume 
containing the data space; you must also specify SPACE 
and no other entry type parameters. 


password 
specifies a password when the entry to be listed 
is password protected and a password is not 
specified with the CATALOG parameter. The 
password can be any of the entry's passwords. 
The entry's protection attributes are listed only 
when you specify the entry's Cor its catalog's) 
master password. RACF: The alter RACF authority 
to the catalog or entry is required. 


When you don't supply a password for a 


password-protected entry, the operator or TSO JOR 
terminal user is prompted for the entry's 
password. You cannot supply a password for these rd 


types of entries: non-VSAM data set, generation 
data group, alias, user catalog connector, or 
data space. 


Abbreviation: ENT 


LEVEL( level ) 
specifies that all entries that match the level of 
qualification specified by Clevel) are to be listed, 
irrespective of the number of additional qualifiers. 
If a generic level name is specified, only one 
qualifier replaces the *. The * must not be the last 
character specified in the LEVEL parameter. 
LEVELCA.*®) will give you an error message. 


Abbreviation: LVL 





: Suppose a 


=< - LES Oo wah ay 2 oe =Rahe a my —3°A= i ! 
catalog contains the following names: 





1. A.A.B 

2. A.B.B | 
3. A.B.B.C | 
G. A.B.B.C.C | 
5. A.C.C | 
6. A.D 

7. A.E . 

8. A 
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If ENTRIESCA.%) is specified, entries 6 and 7 will be 
listed. If ENTRIESCA.®.B) is specified, entries 1 and 2 
will be listed. If LEVELCA.*®.B) is specified, entries l, 
2» 3, and 4 will be listed. If LEVELCA) is specified, 
entries 1, 2, 3, 4, 5, 6, and 7 will be listed. 





When uSing a generic name with the ENTRIES parameter, 
entries must have one qualifier in addition to those 
specified in the command. 


EXPIRATION( days) 
specifies that entries of the indicated type, such as 
CLUSTER and DATA, are to be listed only if they will expire 
in the specified number of days or earlier. 


days 
specifies the number of days. This value can be 
expressed in decimal, hexadecimal, or binary. If it 
is expressed in either hexadecimal or binary, it must 
be preceded by either 'X! or 'B* and be enclosed in 
Single quotation marks. The maximum number that can 
be specified is 9999 and indicates that all entries 
are to be listed. Any value that exceeds the year 
2000 will default to 99.999lCyyddd). Zero indicates _ 
St ghee entries that have already expired are to be 

isted. 


Abbreviation: EXPIR 


NAME | HISTORY | VOLUME | ALLOCATIONI ALL 
specifies the fields to be included for each entry listed. 
Appendix A, “Interpreting LISTCAT Output Listings™ on 
page 256, shows the listed information that results when 
you specify nothing Cwhich defaults to NAME), HISTORY, 
VOLUME, ALLOCATION, and ALL. 


{ NAME 
( specifies that the name and entry type of the entries 
are to be listed. 


Some entry types are listed along with their 
associated entries. The entry type and name of the 
associated entry follow the listed entry's name. For 
details, see "ASN: Associations Group™ in 

BPP een A, "Interpreting LISTCAT Output Listings" on 
page , 


Note to TSO users: Only the name of each entry 
associated with the TSO user's prefix is listed when 
no other parameters are coded. 


HISTORY 
specifies that only the following information is to be 
listed for each entry: name, entry type, ownerid, 
creation date, expiration date, and for a recoverable 
catalog's entries, the catalog recovery area's volume, 
device type, and control interval number. It can be 
specified for CLUSTER, DATA, INDEX, ALTERNATEINDEX, 
PATH, GENERATIONDATAGROUP, PAGESPACE, and NONVSAM. 


Abbreviation: HIST 


VOLUME 
specifies that the information provided by specifying 
HISTORY plus the volume serial numbers and device 
types allocated to the entries, are to be listed. 
Volume information is only listed for data and index 
component entries, data space (volume) entries, 
Hee lial data set entries, and user catalog connector. 
entries. 


Note to TSO users: Only the name and volume serial 
numbers associated with the TSO user's prefix are 
listed when no other parameters are coded. 
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Abbreviation: VOL OB a 
ALLOCATION (ff 


specifies that the information provided by specifying sy 
VOLUME plus detailed information about the allocation at 


are to be listed. The information about allocation is 
listed only for data and index component entries. 


Abbreviation: ALLOC 


ALL 
specifies that all fields are to be listed. 


NOTUSABLE 


specifies that only those data and index entries with the 
“"unusable™ indicator on are to be listed. A data or index 
component is marked "unusable" when a system failure occurs 
that results in damage to the entry's cataloged 
information. 


When the cataloged information is reset, the damaged entry 
and its backup copy Cin the catalog recovery area) might 
not match when the space allocation information is 
compared. VSAM marks the catalog entry “unusable™ until 
the space allocation information is corrected. See 


Administration Guide for more details. 
Abbreviation: NUS 


OUTFILE( ddname) 


specifies a data set, other than the SYSPRINT data set, to 
receive the output produced by LISTCAT (that is, the listed 
catalog entries). Completion messages produced by access 
method services are sent to the SYSPRINT data set, along 
with your job's JCL and input statements. 


ddname identifies a DD statement that describes the 
alternate target data set. If OUTFILE is not specified, 
the entries are listed in the SYSPRINT data set. If an 
alternate data set is specified, it must meet the 
ees in "For an Alternate Target Data Set™ on 
page ; 


Abbreviation: OFILE 
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LISTCAT EXAMPLES 





Listing a Key-Sequenced Cluster's Entry in a Catalog: Example 1 
In this example, a key~sequenced cluster entry is listed. 


//LISTCAT1 JOB ie 

//STEPI EXEC PGM=IDCAMS 

Z/SYSPRINT DD SYSOUT=A 

S/SSYSIN DD % 

LISTCAT - 

ENTRIESCD40.EXAMPLE.KSDS1) - 
CLUSTER - 
ALL 

7K 


The LISTCAT command lists the cluster's catalog entry. It is 
assumed that the high level of the qualified cluster name is the 
same as the alias of the catalog D27UCAT1; this naming 
convention directs the catalog search to the appropriate 
catalog. Its parameters are: 


e ENTRIES, which identifies the entry to be listed. 


@ CLUSTER, which specifies that only the cluster entry is to 
be listed. If CLUSTER had not been specified, the cluster's 
data and index entries would also be listed. 


e ALL, which specifies that all fields of the cluster entry 
are to be listed. 


Alter a Catalog Entry, Then List the Modified Entry: Example 2 


( In this example, the free space attributes for the data 

= component CKSDATA) of cluster MYDATA are modified. Next, the 
cluster entry, data entry, and index entry of MYDATA are listed 
to determine the effect, if any, the modification has on the 
cluster's other attributes and specifications. 


//LISTCAT2 JOB ee 
77 JOBCAT DD DSNAME=D27UCAT1, DISP=SHR 
//STEPI EXEC  PGM=IDCAMS 
/7SYSPRINT DD SYSOUT=A 
Z/7SYSIN DD xX 
ALTER - 
D40.KSDATA - 
FREESPACEC10 10) 
IF LASTCC = 0 - 


AT - 
ENTRIESCD40.MYDATA) - 
ALL 

/X® 


Job control language statement: 


e JOBCAT DD, which makes a catalog available for this job: 
D27UCAT1. 


The ALTER command modifies the free space specifications of the 
key-sequenced VSAM cluster DGO.MYDATA. The command's parameters 
are: 


@ D40.KSDATA, which is the entryname of the data component 
being altered. DGO.KSDATA identifies the data component of 
a key~sequenced VSAM cluster, DGO.MYDATA. In order to alter 
a value that applies only to the cluster's data component, 
such as FREESPACE does, you must specify the data 
component's entryname. 


am 
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e FREESPACE, which specifies the new free space percentages _ 
for the data component's control intervals and control 
areas. 


The IF ... THEN command sequence verifies that the ALTER command 
completed successfully before the LISTCAT command executes. 


The LISTCAT command lists the cluster's entry and its data and 
index entries. Its parameters are: 


° ENTRIES, which specifies the entryname of the object being 
listed. Because DG0.MYDATA is a key~sequenced cluster, the 
tong entry, its data entry, and its index entry are 

isted. 


® ALL, which specifies that all fields of each entry are to be 
listed. 
List Catalog Entries: Example 3 


This example illustrates how all catalog entries with the same 
generic name are listed. 


“/LISTCATS JOB 


77 SOBCAT DD DSNAME=USERCAT4, DISP=SHR 
//STEPI EXEC PGM=IDCAMS 
//7SYSPRINT DD SYSOUT=A 
S/7SYSIN DD % 
LISTCAT - 

ENTRIESCGENERIC.%.BAKER) - 

ALL 
7% 


Job control language statement: 


e JOBCAT DD, which makes a catalog available for this job: 
USERCAT4. 


The LISTCAT command lists each catalog entry with the generic 
name GENERIC.*.BAKER, where "¥" is any 1~ to 8-character simple 
name. Its parameters are: 


® ENTRIES, which specifies the entryname of the object to be 
listed. Because GENERIC.*®.BAKER is a generic name, more 
than one entry might be listed. 


6 ALL, which specifies that all fields of each entry are to be 
listed. 
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LISTCRA 


The LISTCRA command lists or compares the contents of a given 
catalog recovery area (CRA). This command is for use with 


The format of the LISTCRA command is: 


LISTCRA INFILE(ddnamelf ddname...1) 


PCATALOG catnamel “password! 
[COMPARE | 


NOCOMPARE] 
[DUMP | NAME |[SEQUENTIALDUMP] 
[MASTERPW( password) ] 
COUTFILE(ddname)] 





LISTCRA can be abbreviated: LISTR 


LISTCRA PARAMETERS 


Required Parameters 


INFILE(ddnamelf ddname...1) 
identifies the DD statement(s) that describes the catalog 
recovery area's volume. You can list or compare more than 
one catalog recovery area. However, if COMPARE is 
specified, all volumes whose catalog recovery areas are 
listed must be owned by the same VSAM catalog. 


Note: The ddname list for the INFILE parameter is limited 
to 9 ddnames. 


Optional Parameters 
CATALOG(catnamel/ 


Password] ddname) 
identifies the catalog that owns the volume(Cs) identified 
with the INFILE parameter. The CATALOG parameter is 
required when you specify the COMPARE option either with 
the DUMP or NAME output format. CATALOG cannot be 
specified with SEQUENTIALDUMP. 


When the catalog is password protected, you must 
supply the catalog's master password. The password is 
required, even though the master catalog's password 
may have been supplied in the MASTERPW parameter. 
RACF: The alter RACF authority to the catalog is 
required. 


When CATALOG is specified, you must describe and 
allocate the catalog to be compared with a DD 
statement. ddname identifies the catalog's DD 
statement, and is required when you specify the 
CATALOG parameter. You cannot specify JOBCAT or 
STEPCAT as the ddname. However, if the catalog being 
compared is not the VSAM master catalog, you must also 
identify the catalog by a STEPCAT or JOBCAT DD 
statement in addition to the DD statement referenced 
by ddname. 


If the catalog information is entered incorrectly, the 
Sepa eae default is taken, and all the CRA records are 
isted. 


Abbreviation: CAT 
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COMPARE | NOCOMPARE 


specifies whether the list is to be limited to those ££ 
entries in the catalog recovery area that do not match Ca 
their corresponding catalog entries. Sa” 
COMPARE 


When you specify COMPARE, only those entries that do 
not match are listed. All the catalog's entries are 
compared, except the catalog's self-describing 
records. You must identify the catalog (that contains 
the catalog entries that are still to be compared) 
with the CATALOG parameter. 


The COMPARE parameter cannot be specified if you 
specify SEQUENTIALDUMP. 


Note: If you specify the COMPARE option, page space 
entries will always result in a mismatch. This is a 
normal condition and does not require any corrective 
action. The mismatch is caused by the OPEN indicator 
not being set in the page space record in the CRA, 
whereas it is set in the catalog. 


Abbreviation: CMPR 


NOCOMPARE 
When you specify NOCOMPARE Cor allow it to default), 
all the catalog recovery area's records are listed. 


Abbreviation: NCMPR 


See Appendix B, "Interpreting LISTCRA Output Listings” on 
page 301 for examples of each type of output listing. 


DUMP | NAME | SEQUENTIALDUMP 
specifies the amount of cataloged information to be listed. 


DUMP 
specifies that each listed entry is printed in its 
entirety in both hexadecimal and character form. 
Records are listed alphamerically and grouped by 
components. 


NAME 
specifies that each listed entry includes only the 
entry's name, its volume serial numbers, and the name 
and entry type of each associated entry. All listed 
entries are sorted alphamerically and grouped. 


SEQUENTIALDUMP 
specifies that each listed entry is to be printed in 
its entirety in both hexadecimal and character form. 
Records are listed in the sequence in which they 
appear in the catalog recovery area. 


Abbreviation: SDUMP 


The DUMP, NAME, SEQUENTIALDUMP, COMPARE, and NOCOMPARE 
options can be specified to produce five different kinds of 
output listing. See Appendix B, "Interpreting LISTCRA 
ete Listings™ on page 301, for examples of each type of 
isting. 


MASTERPW( password) 
specifies the master catalog's master password. This 
parameter is required when the master catalog is 
password-protected. 


Abbreviation: MRPW 
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OUTFILE( ddname) 


identifies the DD statement that describes an alternate 
target data set. See "For an Alternate Target Data Set™ on 
page 10 for more details about alternate target data sets. 


When OUTFILE is not specified, the listing is printed on 
the output device described with the SYSPRINT DD statement. 
When OUTFILE is specified, the listing produced by LISTCRA 
is sent to the alternate target data set; the remainder of 
the access method services output is printed on the output 
device described with the SYSPRINT DD statement. Refer to 
Appendix B, "Interpreting LISTCRA Output Listings" on 

page 301, for an example of the use of the OUTFILE 
parameter. 


Abbreviation: OFILE 
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Listing a Catalog Recovery Area: Example 1 


This example lists in dump format the catalog recovery areas for 
those volumes owned by the VSAM master catalog, AMASTCAT, and 
compares those catalog recovery areas with the actual catalog 
records themselves. 


//\.ISTAREA JOB side 
7/STEPI EXEC PGM=IDCAMS 
S/SYSPRINT SYSOUT=A 
//CRAVOLI DD DISP=OLD, VOL=SER=SG2001,UNIT=DISK 
//CRAVOL2 DD DISP=OLD, VOL=SER=VSEROG, UNIT=DISK 
//CATVOL DD DSNAME=AMASTCAT, DISP=OLD 
/“SYSIN DD 4 
LISTCRA - 
INFILEC - 
CRAVOL1 - 
CRAVOL2) - 
MASTERPNCMCATMRPHW) -— 
COMPARE - 
DUMP - 
CATALOGCAMASTCAT/MCATMRPW CATVOL) 


we 
a 


7X 


Job control language statements: 


° CRAVOL1 DD, which identifies and allocates the volume that 
contains the first catalog recovery area to be listed. 


@ CRAVOL2 DD, which identifies and allocates the volume that 
contains the second catalog recovery area to be listed. 


¢ CATVOL DD, which identifies and allocates the catalog to be 
compared against, and makes the catalog available to LISTCRA 
as a data set. Because this example is listing the master 
catalog, no STEPCAT or JOBCAT DD statement is required. 
However, if the example were listing a user catalog, a 
STEPCAT or JOBCAT DD statement would be required in addition 
ee CATVOL DD statement to describe the user catalog as a 
catalog. 


The LISTCRA command causes the catalog recovery areas on volumes 
$G2001 and VSEROG to be listed and their contents compared with 
the VSAM system catalog AMASTCAT. The LISTCRA command's 
parameters are: 


e INFILE, which is required and specifies the catalog recovery 
areas to be listed by identifying the DD statement that 
describes each CRA's volume. 


e MASTERPW, which specifies the master password of the master 
catalog. This parameter is required in order to open the 
catalog recovery areas for LISTCRA processing. 


e COMPARE, which specifies that the catalog records are to be 
compared with their copies in the catalog recovery areas. 


@ DUMP, which specifies that the results of the record 
comparison (that is, the LISTCRA output listing) are to be 
printed in dump format. 


@ CATALOG, which is required because the COMPARE option was 
specified. This parameter identifies the catalog to be 
compared against by identifying the DD statement that 
describes and allocates the catalog as a data set. 
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( The PRINT command prints VSAM data sets, non-VSAM data sets, and 
‘. catalogs. The format of this command is: 


CINFILE(ddnamel/password]} | 
INDATASET (Centrynamel /password] )} 

[ CHARACTER | DUMP | HEX] 

[FROMKEY (key ) | FROMADDRESS (address) | 


FRONNUMBER(ounber )1SKIP{ number) 1 
[OUTFILE( 
TOKE CCR CHORD OHESel 


address} | 
TONUMBER (number ) | COUNT (number) 1 





PRINT PARAMETERS 


Required Parameters 


INFILE(ddnamel/password]} | 

INDATASET (entrynamel/password] ) 
identifies the data set or component to be printed. If the 
logical record length of a non-VSAM source data set is 
greater than 32760 bytes, your PRINT command will terminate 
with an error message. 


INFILE(ddnamelZ ]) 
specifies the name of the DD statement that identifies 
the data set or component to be printed. 


You can list a base cluster in alternate-key sequence 
ee. by specifying a path name as the data set name in the 
( DD statement. 


Abbreviation: IFILE 


INDATASET (entrynamel/password]) 
specifies the name of the data set or component to be 
printed. If INDATASET is specified, the entryname is 
dynamically allocated. 


You can list a base cluster in alternate-key sequence 
by specifying a path name as entryname. 


If a VSAM data set or component is password 
protected, a password must be supplied. The 
password to be supplied is: 


® The master password of the catalog if you are 
listing a catalog. RACF: The alter RACF 
authority to the catalog is required. 


@ The read- or higher-level password of the 
data set or component if the data set or 
component is not a catalog. RACF: The read 
or higher RACF authority to the data set or 
component 1s required. 


° The master password of the cluster if you are 
listing a component of a password-protected 
cluster. RACF: The alter RACF authority to 
the cluster is required. 


Passwords are applicable only to VSAM data sets and 
their components. 


Abbreviation: IDS 
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Optional Parameters 




















CHARACTER | DUMP | HEX \g | 
specifies the format of the listing. es 
CHARACTER ; ; : 
specifies that each byte in the logical record is to 
be printed as a character. Bit patterns not defining 
a character are printed as periods. Key fields are 
listed in character format (see Figure 4). 
Abbreviation: CHAR 
YOCANS SYSTEM SERVICES TIME: 19:26:13 03/08/75 PAGE 6 
LISTING OF DATA SET -EXAMPLE.LISTC.DATA 
RBA OF RECORD - 0 
ABCD00000000000 1 ABCDEFGHI JK LMNOPGRSTUVNXYZ0 1 23456 78 9ABCDEFGHI JK LMNOPQRS TUVNXYZO 1 23456 78 SABCDEFGHI JK LMNOPGRS TUVNXYZ012345 
6 769ABCDEFGHI JK LMNOPGRS TUVWXYZ0 12 3456 78 9ABCDEF GHI JK LHNOPQRSTUVNXYZ0 123456 78 9ABCDEFGHI JK LMNOPQRSTUVNXY 201 2 3456 76 9ABCOEFGH 
TUK UMNOPGRS TUVWXYZ0 1 23456 76 9ABCOEFGHI JK LIMIOPQRSTUVNZYZ0 123456 78 SABCDEFGHI JK LMNOPQRS TUVWXYZ 1 2 3456 789ABCOEFGHI UK LMNOPQRST 
UVICKYZO 123456 TE9ABCOEFGHIJKLMNOPQRST.... 
Figure 4. Example of Character Format of PRINT Command 
DUMP a, ; ; ; 
specifies that each byte in the logical record is to 
be printed in both hexadecimal and character format. 
In the character portion of the listing, bit patterns 
not defining a character are printed as periods. Key 
fields are listed in hexadecimal format (see 
Figure 5). K 
Me ee. 
IOCAMS SYSTEM SERVICES TIME: 19:25:14 03/08/75 PAGE 2 
LISTING OF DATA SET -EXAMPLE.LISTC 
KEY OF RECORD - FOFOFOFOFOFOFOFOFOFOFOF! | E 
6000 C1C2C3C4 FOFOFOFO FOFOFOFO FOFOFOF1! C1C2C3C4 C5C6C7C8 C9D102D3 DGD5D607 #ABCD000000000001 ABCDEFGHY JKLMNOPS 
0020 QO09EZE3 ESESEOE7 ESEOFOF] F2F3FGFS FOF7F8F9 CIC2C3C4 C5SC6C7CS C9D1N2ZD3 #QRSTUVWXYZ0123456 76 9ABCDEFGHIJKL® 
6040 04050607 DED9EZES ESESEOE7 FOFOFOF] F2F3F4FS FOF7FEF9 C1C2C3C% CSC6C7C&8 *#MNOPQRSTUVWXYZ012 3456 769ABCDEFGH# 
0060 €90102D3 04050607 D&D9EZES ESESE6GE7 ESESFOF1] F2F3FOFS FOF 7FEF9S C1C2C3C4 #I JK LPMNOPQRSTUVWXYZ0123456 78 9ABCOe 
0080 CSC6C7CE C9D1D203 04D506D7 DSD9EZE3 ESESESE7 ESESFOF] F2F3FGFS FOFT7ESF9  xEFCHIJKLMNOPGRSTUVWXYZ01234656789% 
COCAG C1IC2C3C4 CSC6C7C& C9D1D203 D4D506D7 DS8D9EZE3 EGESEGE7 ESESFOF! F2F3F4FS  *ABCOEFGHIJKLMNOFQRSTUVWNXYZ0O123465% 
COCO §3=—s-« FOF 7FOFO CIC2C3C4% C5C6C7C8 C9D10203 04050607 DSD9EZE3 ESESE6E7 ESESFOF1 #6 789ABCDEFGHIJKLMNOPQRSTUVWXYZO1# 
CCEG 3 = F2E3F4FS FOF7FEF9 CIC2C3C% CSC6C7C8 C9D1D2D3 D4D5D6D7 DSDSEZE3 EGESE6E7  #234567S9ABCDEFGHI JK LMNOPCRSTUVWX# 
0100 ESESFOF] F2F3F4FS FOF7FEF9 C1C2C3C4 C5C6C7C& C9D102D3 D4D506D7 DSDSEZE3 *YZ0123456 789ABCDEFGHI JKLMNOPQRST# 
0320 4 ESESEGE7 ESESFOF!L F2F3F4F5 FOF7F8F9 C1C2C3C4 C5C6C7C8 C9D1D2D3 D4GD50607 #UVWXYZ0123456 789ABCDEFGHI JKLIMOPH 
0140 OBDSEZES ESESEGE7 ESESFOF] F2F3FGF5 F6F7FEF9 C1C2C3C% CS5C6C7C8 C9D010203 *GRSTUVWXYZ0123456 769ABCDEFGHIJKL® 
0160 04050607 DED9EZE3 ESESEGE7 ESESFOF1\ F2F3F4FS FOF7FEF9 C1IC2C3C4 C5C6C7C8  #*MNOPQRSTUVWXYZ0123456 789ABCDEFGH# 
0160 €9D102D3 04050607 DSD9EZES 00000000 *#IJKLMNOPQRST.... Ps 
Figure 5. Example of Dump Format of PRINT Command 
HEX 
specifies that each byte in the logical record is to 
be printed as two hexadecimal digits. Key fields are 
listed in hexadecimal format (see Figure 6 on 
page 219). 
— 
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IOCAMS SYSTEM SERVICES TIME: 19:26:13 03/08/75 PAGE 4% 


LISTING OF DATA SET -EXAMPLE.LISTC.DATA 


RBA OF RECORD - 0 

C1C2C3C4F OF OF OF OF OF OF OF OF OF OF OF 1C1C2C3C4C5C6C7C8C 9D 102D 304D5D6D 7D8D 9E2E 3E4E SEGE 7E SE OF OF LF 2F SF GF SF OF 7FS8F 9C1IC2C3C4C5C6C7CS 
C90 1020 30405060 7080 9E 2D 304E5E6E 7E SE OF OF LF 2F SF4F SF OF 7F BF IC 1C2C3C4C5C6C7C8C 9D 1020 30405060 7080 9E 2E SESE SEGE 7ESE OF OF IF 2FSF4OFS 
FOF 7F OF 9C 1C2C3C4C5C6C7C8C 9D 102030405060 7060 9E 2E SESESEGE 7ESE SF OF LF 2F SFGF SF OF 7F BF 9CIC2C3C4C5C6C 7C8C 90 1D 2D 304D506D 7D8D 9E2ES3 
ESESESE 7EGE OF OF LF 2F SF4FSFOF 7F SF 9CI1C2C3C4C5C6C7C8C 9D 1D20 3D4D506D 7D6D 9E 2E SESESEGE 7ESE OF OF LF 2F SF4FSFOF 7F OF 9CIC2C3C4C5C6C7C8 
C90 102030405060 7D6D 9E 2E 3ESESEGE 7EGE OF OF LF 2F SF 4F SF6F 7F OF 9CIC2C 3C4C5C6C7C8C 90 1020 30405060 7080 9E 2E 3E GE SEGE 7EGE SF OF LF 2F 3F4FS 
FOF 7F OF 9C 1C2C 3C4C5C6C 7C8C 9D 1020 30405060 7080 9E 2E SEGESEGE 7ESE OF OF LF2F SF OF SF OF 7F BF 9CIC2C3C4C5C6C7C8C 90 102030405060 7080 9E2E3 
ESESEGE 7EGE OF OF LF 2F SESFS F6F 7F OF 9C 1C2C3C4C5C6C 7C8C 9D 1020 304D506D 708D 9E 2E 300000000 


Figure 6. Example of Hexadecimal Format of PRINT Command 


FROMKEY (key) | FROMADDRESS (address) | 
FROMNUMBER( number ) [SKIP (number } 
specifies the location in the data set being listed from 
which listing is to start. If you do not specify a value, 
the listing begins with the first logical record in the 
data set or component. The only value that can be 
specified for a SAM data set is SKIP. 


The starting delimiter must be consistent with the ending 
delimiter. For example, if FROMADDRESS is specified for 
the starting location, use TOADDRESS to specify the ending 
location. The same is true for FROMKEY and TOKEY, and 
FROMNUMBER and TONUMBER. 


FROMKEY (key ) 
specifies the key of the first record you want listed. 
You can specify generic keys (that is, a portion of 
the key followed by *)}. If you specify generic keys, 
listing begins at the first record whose key matches 
that portion of the key you specified. 


You cannot specify a Key longer than that defined for 
the data set. If you do, the listing is not 
performed. If the specified key is not found, the 
eee key is used as the starting point for the 
isting. 


FROMKEY can be specified only when an alternate index, 
a key~sequenced VSAM data set, a catalog, or an 
alpen sequential CISAM) non-VSAM data set is being 
printed. 


Key 


can contain 1 to 255 EBCDIC characters. 
Abbreviation: FKEY 


FROMADDRESS (address) 
specifies the relative byte address (RBA) of the first 
record you want listed. The RBA value must be the 
beginning of a logical record. If you specify this 
parameter for a key-~sequenced data set, the listing 
will be in physical sequential order instead of in 
logical sequential order. 


FROMADDRESS can be specified only for VSAM 
key~sequenced or entry~sequenced data sets or 
components. FROMADDRESS cannot be specified when the 
data set is accessed through a path or for a 
key~sequenced data set with spanned records if any of 
those spanned records are to be accessed. 


Abbreviation: FADDR 
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PRINT 


FROMNUMBER( number ) 
specifies the relative aeepnd number of the first 
record you want printed. FROMNUMBER can only be 
specified for VSAM relative record data sets. 


Abbreviation: FNUM 
SKIP(number) 


specifies the number of logical records you want to 
skip before the listing of records begins. For 
example, if you want the listing to begin with record 
number 500, you specify SKIPC499). SKIP should not be 
specified when you are accessing the data set through 
a path; the results are unpredictable. 





can be expressed in decimal (€n), hexadecimal (X'n'), 
or binary (B'n"). The expression cannot be longer 
than one fullword (8 decimal or hexadecimal numbers, 
or 32 binary numbers). 


OUTFILE(ddname) 
identifies a target data set other than SYSPRINT. For 
ddname, substitute the name of the JCL statement that 
identifies the alternate target data set. 


The access method services target data set for listings, 
which is identified by the ddname SYSPRINT, is the default. 
The target data set must meet the requirements stated in 
"For a Target Data Set™ on page 10. 


Abbreviation: OFILE 


TOKEY(key) | TOADDRESS (address) | 

TONUMBER( number ) | COUNT (number ) 
specifies the location in the data set being listed at 
which you want the listing to stop. If no value is 
specified, the listing ends with the logical end of the 
data set or component. The only value that can be 
specified for a SAM data set is COUNT. The location at 
which the listing is to stop must follow the location at 
which the listing is to begin. 


The ending delimiter must be consistent with the starting 
delimiter. For example, if FROMADDRESS is specified for 
the starting location, use TOADDRESS to specify the ending 
location. The same is true for FROMKEY and TOKEY, and 
FROMNUMBER and TONUMBER. 


TOKEY (key) 
specifies the key of the last record to be listed. 
You can specify generic keys (that is, a portion of 
the key followed by *). If you specify generic Keys, 
listing stops after the last record is listed whose 
key matches that portion of the Key you specified. If 
you specify a key longer than that defined for the 
data set, the listing is not performed. 


If the specified key is not found, the next lower key 
is used as the stopping point for the listing. 


TOKEY can be specified only when an alternate index, a 
key~sequenced VSAM data set, a catalog, or an indexed 
sequential CISAM) non-VSAM data set is being printed. 


can contain 1 to 255 EBCDIC characters. 
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TOADDRESS (address) 
epecifies the relative byte address CRBA) of the last 
record you want listed. 


Unlike FROMADDRESS, the RBA value does not need to be 
the beginning of a logical record. The entire record 
containing the specified RBA is printed. If you 
specify this parameter for a key~sequenced data set, 
the listing will be in physical sequential order 
instead of in logical sequential order. 


TOADDRESS can be specified only for VSAM key~sequenced 
or entry~sequenced data sets or components. TOADDRESS 
cannot be specified when the data set is accessed 
through a path. TOADDRESS cannot be specified for a 
key-~sequenced data set with spanned records if any of 
those spanned records are to be accessed. 


Abbreviation: TADDR 


TONUMBER( number ) 
specifies the relative record number of the last 
record you want printed. TONUMBER can only be 
specified for a VSAM relative record data set. 


Abbreviation: TNUM 
COUNT (number ) 


specifies the number of logical records to be listed. 
COUNT should not be specified when you are accessing 
the data set through a path; the results are 
unpredictable. 


can be expressed in decimal (n), hexadecimal (X'n'"), 
or binary CB'n'); the expression cannot be longer than 
one fullword (8 decimal or hexadecimal numbers, or 32 
binary numbers). 
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| Print a Catalog: Example 1 


This example shows how to print a catalog. You may find this 
| function of the PRINT command helpful in the event of a problem 
with your catalog. 


//PRINTS JOB... 

//JOBCAT DD £DSNAME=USERCAT4, DISP=OLD 
//STEPI EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SYSIN DD x 


/* PRINT THE ENTIRE CATALOG */ 
PRINT - 


INDATASET CUSERCAT4) 
1% 


Job control language statement: 


@ JOBCAT DD, which is required and which describes and 
allocates the user catalog to be printed. 


The PRINT command prints the entire catalog, because there are 
no delimiting parameters specified. 


Print a Catalog: Example 2 


This example shows various ways to print a catalog. You may 
find this function of the PRINT command helpful in the event of 
a problem with your catalog. 


//PRINTS JOB... ee 
//JOBCAT DD  DSNAME=D27UCAT1,DISP=OLD — 
//STEP1 EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//SYSIN. DD 


eee LOW KEY RANGE OF THE CATALOG X7 


INDATASETCD27UCAT1) - 
TOKEY (X'3F") 


7% a HIGH KEY RANGE OF THE CATALOG X/ 
INDATASETCD27UCAT1) - 
FROMKEY (X*40") 


7® PRINT A SPECIFIC RECORD X/ 
7*® FROM THE LOW KEY RANGE X/ 
PRINT - 
INDATASET(D27UCAT1) - 
FROMKEY CX*OO000000E") - 
COUNT (1) 


/*® PRINT THE ENTIRE CATALOG X/ 
PRINT - 


INDATASET CD27UCAT1) 
7% 


The job control language statements are: 


e JOBCAT DD, which is required and which describes and 
allocates the user catalog to be printed. 


The first PRINT command prints the low-key range of the catalog. 
Its parameters are: 


e INDATASET, which specifies the name of the catalog to be J 
printed. 
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PRINT 


® TOKEY, which specifies that printing is to terminate after 
eo reaching a record whose key is greater than X'SF! Cin its 
( first byte). The low-key range of a VSAM catalog contains 
records with a range of keys having a value from X'00!' to 
X'3F*" in the first byte. 


The second PRINT command prints the high-key range of the 
catalog. Its parameters are: 


e INDATASET, which specifies the name of the catalog to be 
printed. | 


@ FROMKEY, which specifies that printing is to begin at the 
first record whose Key is X'40' or greater Cin its first 
byte). The high-key range of a VSAM catalog contains 
records with a range of keys having a value from X‘'40* to 
X'FF' in the first byte. 


The third PRINT command prints one catalog record from the 
low-key range of the catalog. Its parameters are: 


e INDATASET, which specifies the name of the catalog to be 
printed. 


® FROMKEY, which specifies that printing is to begin with the 
record whose key is X'0000000E in the first 4 bytes. 
Records in the low-key range of a VSAM catalog have the 
number of the containing control interval as the first 4 
bytes of their key. Records are 505 bytes in length and 
each record is contained in a 512-byte control interval. 


e COUNT, which specifies that only one record is to be 
printed. 


The fourth PRINT command prints the entire catalog, because 
( there are no delimiting parameters specified. 


Print a Key-Sequenced Cluster'’s Data Records in a Catalog: Example 3 


In this example, the data records of a key~sequenced cluster, 
D40.EXAMPLE.KSDS1, are printed in dump format. That is, each 
character of the record is printed in its hexadecimal and 
alphameric forms. 


//7PRINTI JOB... 
S/ STEP EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
“7 SYSIN DD % 
PRINT - 
INDATASET CD40. EXAMPLE.KSDS1) 
7% 


‘The PRINT command prints data records of the Key~sequenced 
cluster, D40.EXAMPLE.KSDS1. Its parameter is: 


e INDATASET, which names the data set to be printed. Because 
the data set is cataloged in D27UCAT1 and the high-level 
qualifier of the data set is the name of the alias of 
D27UCAT1, access method services can dynamically allocate 
the cluster without the need of JOBCAT or STEPCAT DD 
statements. 


Because neither FROMADDRESS, FROMKEY, SKIP, TOKEY, TOADDRESS, or 
COUNT is specified, access method services assumes that all the 
cluster's data records are to be printed. 


Because neither HEX nor CHAR was specified, access method 
services prints each record in the DUMP format. An example of 
the printed record is shown in Figure 7 on page 224. 
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PRINT 


KEY OF RECORD - OOFOFOFOFOF IC9E240C4C140SCC6C9 foo 


C00@ OOFOFOFO FOFICSE2 40C4C140 SCC6C9DS  C540C9FO COFSFOSC 40F5F040 DOCSC3D6 *.00001IS DA *FILE ToDso* 50 RECO™ e - 2 
C020 O9C4E240 D6CEGOF6 F94OC3CS CLO9E240 E6C9ESCE 40D2C5ES 40C 90540 D706E240 *RDS OF 69 CHARS WITH KEY IN POS # Qo 
0040 FIGOFIFI 48000000 00000000 00000000 oS oe) aera arene 


Figure 7. An Example of the Printed Record in DUMP Format CResult of Print Command) 


Copy Records from a Non-VSAM Data Set into an Entry~-Sequenced VSAM Cluster, Then 
Print the Records: Example 4% 


In this example, the first 15 records from a non-VSAM data set, 
EXAMPLE.NONVSAM, are copied into an entry-sequenced cluster, 
D50.EXAMPLE.ESDS1. If the records were copied correctly, the 
cluster's records are printed in hexadecimal format. Finally, 
even if the records were not copied correctly, the non-VSAM data 
set's first 15 records are printed in character format. 


 SZ/PRINT2 JOB... 
4/ SOBCAT DD DSNAME=USERCAT4, DISP=SHR 
// DD DSNAME=D27UCAT2, DISP=SHR 
//STEP1 EXEC PGM=IDCAMS 
//NSDSET2 DD DSNAME=D50.EXAMPLE.ESDS1,DISP=OLD 
//SYSPRINT DD SYSOUT=A 
S/3YSIN DD xX 
REPRO - 

INDATASETCEXAMPLE.NONVSAM) - 

OUTFILECVSDSET2) - 

COUNT(15) 


IF LASTCC = 0 - 
THEN - 
PRINT - 
INFILECVSDSET2) - 
HEX 


PRINT ~- 
INDATASETCEXAMPLE.NONVSAM) - 
COUNT(15) - 
CHARACTER 

7% 


Job control language statements: 


e JOBCAT DD, which makes two catalogs available for this job: 
USERCAT4 and D27UCAT2. Concatenated JOBCAT DD statements 
were used to identify both catalogs. 


6 VYSDSET2 DD, which identifies the entry-sequenced VSAM 
eer D50.EXAMPLE.ESDSI1, that the records are copied 
into. 


Note: If the AMP=(BUFND=n) parameter was specified, 
performance would improve when the data set's records are 
accessed. BUFND was allowed to default in this example, 
because only 15 records are being processed. 


The REPRO command copies the first 15 records from the source 
data set, EXAMPLE.NONVSAM, into the target entry~sequenced 
cluster, D50.EXAMPLE.ESDS1. Its parameters are: 


e INDATASET, which identifies the source data set, 
EXAMPLE.NONVSAM. Because a JOBCAT DD statement is included 
with the job, VSAM will search for the catalog entry 
describing the non-VSAM data set in either USERCAT4 or 
D27UCAT2 user catalog, or in the master catalog. Na 
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° OUTFILE, which points to the VSDSET2 DD statement. The 
YSDSET2 DD statement identifies the output data set, 
D50.EXAMPLE.ESDS1. VSAM assumes that D50.EXAMPLE.ESDSI1 is 
cataloged either in USERCAT4 or D27UCAT2 user catalog, or in 
the master catalog. 


e COUNT, which specifies that 15 records are to be copied. 
Because the SKIP parameter was not specified, access method 
services assumes that the first 15 records are to be copied. 
The records are always added after the last record in the 
output data set. 


The IF ... THEN command sequence verifies that the REPRO command 
completed successfully before the first PRINT command executes. 


The first PRINT command prints the records in the 
entry~sequenced cluster, D50.EXAMPLE.ESDS1. Its parameters are: 


° INFILE, which points to the VSDSET2 DD statement. The 
VSDSET2 DD statement identifies the cluster, 
D50.EXAMPLE.ESDS1. VSAM assumes that the cluster is 
cataloged either in the USERCAT4 or the D27UCAT2 user 
catalog, or in the master catalog. 


e HEX, which specifies that each record is to be printed as a 
group of hexadecimal characters. An example of the printed 
record is shown in Figure 8. 


RBA OF RECORD - 0 
C2D6E 8650 940404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040404040 
4040404040404040404040404040404040404040 


Figure 8. An Example of the Printed Record in Hexadecimal (Result of PRINT Command) 


Note: The IF ... THEN command sequence ends with the HEX 
parameter, because no continuation character follows this 
parameter. If you want two or more access method services 
commands to execute only when the IF statement is satisfied, 
enclose the commands ina DO...END command sequence. 


The second PRINT command, which executes even if the REPRO 
command failed, prints the first 15 records of the non-VSAM data 
set, EXAMPLE.NONVSAM. Its parameters are: 


® INDATASET, which identifies the non-VSAM data set 
EXAMPLE.NONVSAM. VSAM will search for the catalog entry in 
oe USERCAT4 or D27UCAT2 user catalog or in the master 
catalog. 


e COUNT, which specifies that 15 records are to be printed. 
Because SKIP was not specified, access method services 
assumes that the first 15 records are to be printed. 

° CHARACTER, which specifies that each record is to be printed 


as a group of alphameric characters. An example of the 
printed record is shown in Figure 9. 


RECORD SEQUENCE NUMBER - 3 
CLARK 


Figure 9. An Example of a Printed Alphameric Character Record (Result of PRINT 
Command) 
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REPRO 


The REPRO command copies VSAM and non-VSAM data sets, copies a 
catalogs, and unloads and reloads VSAM catalogs. The format of 4 
this command is: | 


CINFILE( ddnamel /password] 
[ ENVIRONMNENT(DUMMY)])] 
INDATASETlentrynamel/ 
c Sy Altea ap eather 
{OUTFILE( ddnamel /password]) | 
OUTDATASET (entrynamel/password1)} 
[SYSTEMKEYNAME[( )1)] 
CFROMKEY (key) | FROMADDRESS (address) | 
FROMNUMBER Coumber) | SKI P(count)] 
[REPLACEI|INO 
[REUSE |NOREUSE] 
[ TOKEY (key) |] TOADDRESS (address) ] 
TONUMBER( number ) |COUNT(count)] 


[ENCIPHER 
(fEXTERNALKEYNAME(key name) | 
EN TERNS ERE YMAME (key pene) |PRIVAYEKEYS 
C[CIPHERUNIT (number ]1)1 
EDATAKEYE ALE (ddname } | DATAKEYVALUE(value)1 
[SHIPKEYNAMES(key namel key name...1)]1 
[ STOREDATAKEY | ] 
[STOREKEYNAME (key name) 1 
[USERDATA(value)J1)1 

[DECIPHER 
({DATAKEYFILE( ddname) | 
DATAKEYVALUE (value) [SYSTEMKEY] 
[SYSTEMDATAKEY(value)1 





Note: The parameters ENCIPHER and DECIPHER apply only with the 3 | 
IBM Programmed Cryptographic Facility (€5740~-XY5) or the IBM et 
Cryptographic Unit viele A ee XY6). (For more information, 

see VSAM Administration Guide 


REPRO PARAMETERS 


Required Parameters 


INFILE(ddnamel/password1][ ENVIRONMENT(DUMMY)1)| 

INDATASETCentrynamel/password1[ ENVIRONMENT(DUMMY)] ) 
identifies the source data set to be copied. If the 
logical record length of a non-VSAM source data set is 
greater than 32760 bytes, your REPRO command will terminate 
with an error message. 


INFILE(ddnamel /password]) 
specifies the name of the DD statement that identifies 
the data set to be copied. 


You can copy a base cluster in alternate-kKey sequence 
by specifying a path name as the data set name in the 
DD statement. 


‘Abbreviation: IFILE 
INDATASET(Centrynamel/ 


password]) 
specifies the name of the entry to be copied. If 
INDATASET is specified, the entryname is dynamically 
allocated. 


You can copy a base cluster in alternate-key sequence 
by specifying a path name for entryname. 


Abbreviation: IDS 
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Optional Parameters 








REPRO 


is the read- or higher-level password of the data 
to be copied. If the data set is 
password-protected, the read password must be 
supplied. If a catalog is to be copied, the 
master password is required. Passwords are 
applicable only to VSAM data sets. 


ENVIRONMENT (DUMMY) 
specifies that dummy ISAM records are to be copied. 
Dummy records are records with hexadecimal 'FF* in the 
first byte. 


If you do not code the ENVIRONMENT parameter, dummy 
records will be ignored during the. copy operation and 
will not be copied. (See 

for further information. ) 


Abbreviations: ENV and DUM 


OUTFILE( ddnamel /password!] ) |OUTDATASET (entrynamel /password]) 
identifies the target data set. ISAM data sets cannot be 
specified as target data sets. If a VSAM data set defined 
with a record length greater than 32760 bytes is to be 
copied to a sequential data set, your REPRO command will 
terminate with an error message. 


OUTFILE(ddnamel /password] ) 
specifies the name of a DD statement that identifies 
the target data set. 


eer data sets, the data set name can be that of a 
path. } 


If the DD statement identifies a SYSOUT data set, the 
attributes must match those specified in "For a Target 
Data Set" on page 10 


Abbreviation: OFILE 


OUTDATASET (entrynamel/password] ) | 
specifies the name of the target data set. If © 
OUTDATASET is specified, the entryname is dynamically 
allocated. 


For VSAM data sets, entryname can be that of a path. 


specifies the update- or higher-level password 
for a password-protected target data set or path. 


Abbreviation: ODS 


FROMKEY (key ) | FROMADDRESS (address) | 
FROMNUMBER (number ) [SKIP( number ) 
specifies the location in the source data set from which 
copying is to start. If no value is coded, the copying 
begins with the first logical record in the data set. You 
can use only one of the four choices. 


ence parameter that can be used for a SAM data set is 


If you are copying a catalog, none of these parameters can 
be specified; the entire catalog must be copied. 


The starting delimiter must be consistent with the ending 
delimiter. For example, if FROMADDRESS is specified for 
the starting location, use TOADDRESS to specify the ending 
location. The same is true for FROMKEY and TOKEY, and 
FROMNUMBER and TONUMBER. 
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REPRO 


FROMKEY (key ) | 
specifies the key of the first record you want copied. 
You can specify generic keys (that is, a portion of 
the key followed by *). If you specify generic keys, 
copying begins at the first record whose key matches 
that portion of the key you specified. 


You cannot specify a key longer than that defined for 
the data set. If you do, the data set is not copied. 
If the specified key is not found, the next higher key 
is used as the starting point for copying. 


FROMKEY may be specified only when an alternate index, 
a key-~sequenced VSAM data set, or an 

ee lat aleal CISAM) non-VSAM data set is being 
copied. 


key 
can contain 1 to 255 EBCDIC characters. 


Abbreviation: FKEY 


FROMADDRESS (address) 
specifies the relative byte address (RBA) of the first 
record you want copied. The RBA value must be the 
beginning of a logical record. If you specify this 
parameter for Key-sequenced data, the records will be 
copied in physical sequential order instead of in 
logical sequential order. 


FROMADDRESS: 


® Can be coded only for key-~sequenced or 
entry~sequenced data sets or components. 


6 Cannot be specified when the data set is being 
accessed through a path. 


e Cannot be specified for a key~sequenced data set 
with spanned records if any of those spanned) 
records are to be accessed. 


Abbreviation: FADDR 


FROMNUMBER (number ) 
specifies the relative record number of the first 
record you want copied. FROMNUMBER can be specified 
only when you copy a relative record data set. 


Abbreviation: FNUM 
SKIP (number ) 


specifies the number of logical records you want to 
skip before beginning to copy records. For example, 
if you want to copy beginning with record number 500, 
you specify SKIP(C499). 


SKIP should not be specified when you access the data 
set through a path; the results are unpredictable. 


> 
can be expressed in decimal (n), hexadecimal (X'n'"), 
or binary CB'n') form; the expression cannot be longer 
than one fullword (8 decimal or hexadecimal numbers, 
or 32 binary numbers). 


REPLACE | NOREPLACE 
specifies whether a record in the source cluster CINFILE or 
INDATASET) is to replace a record in the target cluster 
COUTFILE or OUTDATASET) when the source cluster is copied 
into the target cluster. 


228 MVS/XA VSAM Catalog: Access Method Services Reference 





na. 
oo 
eos 


HES, Mex 














REPRO 


Because the catalog reload function automatically performs 
a REPLACE function, REPLACE|NOREPLACE is ignored if the 
target data set is a VSAM catalog. 





When the source cluster is copied, its records might have 
keys or relative record numbers identical to the keys or 
relative record numbers of data records in the target 
cluster. When this is the case, the source record replaces 
the target record. 


REPLACE 
When a Key~sequenced data set, other than a catalog, 
is copied, each source record whose key matches a 
target record's key replaces the target record. 
Otherwise, the source record is inserted into its 
appropriate place in the target cluster. 


When a relative record data set is copied, each source 
record whose relative record number identifies a data 
record Crather than an empty slot) in the target data 
set replaces the target data record. Otherwise, the 
source data record is inserted into the empty slot its 
relative record number identifies. 


REPLACE cannot be used if the target data set is 
identified as a path through an alternate index, or if 
the target data set is a base cluster whose upgrade 
data set includes an alternate index defined with the 
unique key attribute. 


Abbreviation: REP 


NOREPLACE 
When a key-sequenced data set, other than a catalog, 
1s copied, target records are not replaced by source 
a records. For each source record whose key matches a 
( : target record's key, a "duplicate record™ message is 
issued. 


When a relative record data set is copied, target 
records are not replaced by source records. For each 
source record whose relative record number identifies 
a target data record instead of an empty slot, a 
"duplicate record" message is issued. 


Abbreviation: NREP 
REUSE | NOREUSE 


specifies whether the target data set is to be opened as a 
forge data set. This parameter is valid only for VSAM 
a ata sets. 


REUSE 
specifies that the target data set, specified with 
OUTFILE or OUTDATASET, is opened as a reusable data 
set regardless of whether or not it was defined as 
reusable with the REUSE parameter. (See the DEFINE 
CLUSTER command description.) If the data set was 
defined with REUSE, its high-used relative byte 
address CRBA) is reset to zero (that is, the data set 
is effectively empty) and the operation proceeds. 


If REUSE is specified and the data set was originally 
defined with the NOREUSE option, the data set must be 
empty; otherwise, the REPRO command terminates with an 
error message. 


Abbreviation: RUS 


am 
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NOREUSE a 
specifies that records are to be written at the end of 


an entry-sequenced data set when OUTFILE or OUTDATASET ¢ ~ 
| identifies a nonempty data set. i | 


: Abbreviation: NRUS 


TOKEY( key) | TOADDRESS (address) | 

TONUMBER (number ) | COUNT (number ) 
specifies the location in the data set being copied at 
which copying is to end. The location at which the copying 
is to end must follow the location at which it is to begin. 
If no value is coded, the copying ends with the logical end 
of the data set or component. You can use only one of the 
four choices. | 





The only parameter that can be specified for a SAM data set 
is COUNT. 


If you are copying a catalog, none of these parameters can 
be specified; the entire catalog must be copied. 


The ending delimiter must be consistent with the starting 
delimiter. For example, if FROMADDRESS is specified for 
the starting location, use TOADDRESS to specify the ending 
location. The same is true for FROMKEY and TOKEY, and 
FROMNUMBER and TONUMBER. 


TOKEY (key) 
specifies the key of the last record you want copied. 
You can specify generic keys (that is, a portion of 
the key followed by *). If you specify generic keys, 
copying stops after the first record encountered that 
matches your Key specifications. 


You cannot specify a Key longer than that defined for 
the data set. If you do, the data set is not copied. a OX 
If the specified key is not found, the next lower Key 

1s used as the end point for copying. 


TOKEY can be specified only when an alternate index, a 
key-sequenced data set, or an indexed-sequential 
CISAM) non-VSAM data set is being copied. 


key 
can contain 1 to 255 EBCDIC characters. 


TOADDRESS (address) 
specifies the relative byte address (RBA) of the last 
record you want copied. Unlike FROMADDRESS, the RBA 
value does not need to be the beginning of a logical 
record. The entire record containing the specified 
RBA is copied. 


If you specify this parameter for a key-~sequenced data 
set, the records will be copied in physical sequential 
order instead of in logical sequential order. 


TOADDRESS can be used only with VSAM key-sequenced or 
entry-sequenced data sets or components. TOADDRESS 
cannot be specified when the data set 1S accessed 
through a path. TOADDRESS cannot be specified for a 
key~sequenced data set with spanned records if any of 
those spanned records are to be accessed. 


Abbreviation: TADDR 
TONUMBER( number ) 
specifies the relative record number of the last 
record you want copied. TONUMBER can be specified oe 
only when you copy a relative record data set. a 


Abbreviation: TNUM oY 
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COUNT (number ) 


specifies the number of logical records you want 
copied. COUNT should not be specified when you access 
the data set through a path; the results are 
unpredictable. 


? 
address, number, and count can be expressed in decimal 
€n), hexadecimal (X'n"), or binary (CB'n") form; the 
expression cannot be longer than one fullword (8 
decimal or hexadecimal numbers, or 32 binary numbers). 


CRYPTOGRAPHIC PARAMETERS 


ENCIPHER 
specifies that the target data set is to contain an 
enciphered copy of the source data set. 


The ENCIPHER parameter indicates that the source data set 
is to be enciphered as it is copied to the target data set. 


Abbreviation: ENCPHR 


EXTERNALKEYNAME(key name) | 
INTERNALKEYNAME (Key name) |PRIVATEKEY 
specifies whether keys are managed privately by you, 
or managed by the IBM Programmed Cryptographic 
Facility €5740-XY5) or the IBM Cryptographic Unit 
Support €5740-XY6). 


EXTERNALKEYNAME (kev_name) 
specifies that keys are to be managed by the IBM 
Programmed Cryptographic Facility or the IBM 
Cryptographic Unit Support (5740-XY6) and 
supplies the 1- to 8-character key name of the 
external file key to be used to encipher the data 
encrypting key. The Key is only known by the 
system deciphering it. The Key name and its 
corresponding enciphered data encrypting key will 
only be listed in SYSPRINT if NOSTOREDATAKEY is 
specified. 


Abbreviation: EKN 


INTERNALKEYNANE (key name) 
specifies that Keys are to be managed by the IBM 
Programmed Cryptographic Facility or the IBM 
Cryptographic Unit Support, and supplies the l]- 
to 8-character key name of the internal file key 
to be used to encipher the data encrypting Key. 
The key is retained by the system creating the 
key. The key name and its corresponding 


enciphered data encrypting key will only be 
listed in SYSPRINT if NOSTOREDATAKEY is 
specified. 


Abbreviation: IKN 


PRIVATEKEY 
specifies that the key is to be managed by you. 


Abbreviation: PRIKEY 


CIPHERUNIT(number | 
specifies that multiple logical source records are to 
be enciphered as a unit. number specifies the number 
ef records that are to be enciphered together. By 
specifying that multiple records are to be enciphered 
together, you can improve your security (chaining is 
performed across logical record boundaries) and also 
improve your performance. However, there is a 
corresponding increase in main storage requirements. 
The remaining records in the data set, after the last 
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complete group of multiple records, will be enciphered 

as a group. (CIf number is 5 and there are 22 records Pat 
in that data set, the last 2 records will be c 
enciphered as a unit.) ; 


The value for number may range from 1 to 255. 
Abbreviation: CHPRUN 


DATAKEYFILE( ddname) | DATAKEYVALUE([ value) 
specifies that you are supplying a plaintext (not 
enciphered) data encrypting key. If one of these 
parameters is not specified, REPRO will generate the 
data encrypting key. These parameters are only valid 
when EXTERNALKEYNAME or PRIVATEKEY is specified. If 
INTERNALKEYNAME and DATAKEYVALUE or DATAKEYFILE are 
specified, REPRO will generate the data encrypting key 
Se ae ee nar or DATAKEYFILE will be ignored by 


The plaintext data encrypting key will not be listed 
in SYSPRINT unless PRIVATEKEY is specified and REPRO 
provides the key. 


DATAKEYFILE(ddname) 
identifies a a data set that contains the 
plaintext data encrypting key. For ddname, 
substitute the name of the JCL statement that 
identifies the data encrypting key data set. 


Abbreviation: DKFILE 


DATAKEYVALUE (value) 
specifies the 8-byte value to be used as the 
Fie data encrypting key to encipher the 
ata. 


value may contain 1 to 8 EBCDIC characters or 1 
to 16 hexidecimal characters coded (X'n'). value 
must be enclosed in single quotation marks if it 
contains commas, semicolons, blanks, parentheses, 
or slashes. A single quotation mark must be 
coded as two single quotation marks. With either 
EBCDIC or hexadecimal representation, value is 
padded on the right with blanks (X'40') if it is 
fewer than 8 characters. 


Abbreviation: DKV 


SHIPKEYNAME(key name [key name... ]) 
supplies the 1- to 8-character Key name of one or more 
external file key(s) to be used to encipher the data 
encrypting key. Each key name and its corresponding 
enciphered data encrypting Key will be listed in 
SYSPRINT, but will not be stored in the target data 
set header. The primary use for this parameter is to 
establish multiple enciphered data encrypting Keys to 
be transmitted to other locations for use in 
deciphering the target enciphered data set. This 
parameter is only valid when INTERNALKEYNAME or 
EXTERNALKEYNAME is specified. 


Abbreviation: SHIPKN 


STOREDATAKEY | NO 
specifies whether the enciphered data encrypting key 
is to be stored in the target data set header. The 
key used to encipher the data encrypting key will be 
that identified by INTERNALKEYNAME or EXTERNALKEYNAME. 
This parameter is only valid when INTERNALKEYNAME or cy 
EXTERNALKEYNAME is specified. If the enciphered data fe 
encrypting key is stored in the data set header, it ‘ay 
does not have to be supplied by the user when the data - 
1s deciphered. 
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| Note: A data encrypting Key enciphered under the Keys 
aa identified by SHIPKEYNAME cannot be stored in the 
; header. Therefore, you may want to avoid using 
STOREDATAKEY and SHIPKEYNAME together, because this 
could result in storing header information that is 
unusable at some of the locations involved. 


STOREDATAKEY 
specifies that the enciphered data encrypting Key 
is to be stored in the target data set header. 


Abbreviation: STRDK 


NOSTOREDATAKEY 7 
specifies that the enciphered data encrypting key 
is not to be stored in the target data set 
header. The key name and its corresponding 
enciphered data encrypting Key will be listed in 
SYSPRINT. 


Abbreviation: NSTRDK 


STOREKEYNAME (key name) 
specifies whether a key name for the key used to 
encipher the data encrypting key is to be stored in 
the target data set header. The key name specified 
must be the name by which the key is known on the 
system on which the REPRO DECIPHER is to be performed. 
This key name must be the same one that was specified 
in INTERNALKEYNAME if REPRO DECIPHER is to be run on 
the same system, but can be a different key name than 
that specified in INTERNALKEYNAME or EXTERNALKEYNAME 
if REPRO DECIPHER is to be run ona different system. 


This parameter is only valid when INTERNALKEYNAME or 
amacd EXTERNALKEYNAME is specified. If the key name is 
( stored in the data set header, it does not have to be 
supplied by the user when the data is deciphered. 


Note: key name values identified by the SHIPKEYNAME 
parameter cannot be stored in the header. Therefore, 
you may want to avoid using STOREKEYNAME and 
SHIPKEYNAME tegether, because this could result in 
storing header information that is unusable at some of 
the locations involved. 


Abbreviation: STRKN 


USERDATA(value) 
specifies 1 to 32 characters of user data to be placed 
in the target data set header. This information could 
be used, for example, to identify the security 
classification of the data. 


value may contain 1 to 32 EBCDIC characters. If value 
contains a special character, enclose the value in 
Single quotation marks (for example, 
USERDATAC**CONFIDENTIALX®*)). If the value contains a 
single quotation mark, code the embedded quotation 
mark as two single quotation marks (for example, 
USERDATAC *COMPANY"S*)). 


You can code value in hexadecimal form, where two 
hexadecimal characters represent one EBCDIC character. 
For example, USERDATACX*C3D6DG4D7C1D5E8') is the same 
as USERDATACCOMPANY). The string can contain up to 64 
hexadecimal characters when expressed in this form, 
resulting in up to 32 bytes of information. 


Abbreviation: UDATA 





Chapter 4. Functional Command Format 233 











REPRO 


DECIPHER 
specifies that the target data set is to contain a 
eer ren (deciphered) copy of the enciphered source data 
set. 





The DECIPHER parameter indicates that the source data set 
is to be deciphered as it is copied to the target data set. 
The information from the source data set header is used to 
verify the plaintext data encrypting key supplied, or 
deciphered from the information supplied, as the correct 
plaintext data encrypting key for the decipher operation. 


Abbreviation: DECPHR 


DATAKEYFILE(ddname) | DATAKEYVALUE(value) | SYSTEMKEY 
specifies whether Keys are to be managed privately by 
you, or managed by the IBM Programmed Cryptographic 
Facility or the IBM Cryptographic Unit Support. 


DATAKEYFILE(ddname) 

specifies that the key is to be managed by you, 
and identifies a data set that contains the 
private data encrypting key that was used to 
encipher the data. For ddname, substitute the 
name of the JCL statement that identifies the 
aaa set containing the private data encrypting 
ey. 


Abbreviation: DKFILE 


DATAKEYVALUE (value) | 

specifies that the key is to be managed by you, 

and supplies the l- to 8-byte value that was used 

as the plaintext private data encrypting key to 

encipher the data. For a discussion of how the 

method of supplying the data encrypting Key 

relates to the security of the key, see | | 
a : i eZ 


value can contain 1 to 8 EBCDIC characters. 

value must be enclosed in single quotation marks 
if it contains commas, semicolons, blanks, 
parentheses, or slashes. A single quotation mark 
contained within value must be coded as two 
Single quotation marks. You can code value in 
hexadecimal form, (X'n"). value can contain 1 to 
16 hexadecimal characters, resulting in 1 to 8 
bytes of information. With either EBCDIC or 
hexadecimal representation, value is padded on 
the right with blanks (X'40') if it is fewer than 
8 characters. 


Abbreviation: DKV 


SYSTEMKEY 
specifies that keys are to be managed by the IBM 
Programmed Cryptographic Facility or the IBM 
Cryptographic Unit Support. 


Abbreviation: SYSKEY 


SYSTEMDATAKEY(yalue) 
specifies the 1- to 8-byte value representing the 
enciphered system data encrypting key used to encipher 
the data. This parameter is only valid if SYSTEMKEY 
is specified. If SYSTEMDATAKEY is not specifed, REPRO 
will obtain the enciphered system data encrypting key 
from the source data set header, in which case, 
STOREDATAKEY must have been specified when the data 
set was enciphered. cn 


value may contain 1 to 8 EBCDIC characters. value 


must be enclosed in single quotation marks if it 
contains commas, semicolons, blanks, parentheses, or 
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Slashes. A single quotation mark must be coded as two 
Single quotation marks. You can code value in 
hexadecimal form, (X'n'*). value can contain 1 to 16 
hexadecimal characters, resulting in 1 to 8 bytes of 
information. With either EBCDIC or hexadecimal 
representation, value is padded on the right with 
blanks (€X'40') if it is fewer than 8 characters. 


Abbreviation: SYSDK 


SYSTEMKEYNAME {key name) 


specifies the 1- to 8-character key name of the 
internal key that was used to encipher the data 
encrypting key. This parameter is only valid if 
SYSTEMKEY is specified. If SYSTEMKEYNAME is not 
specified, REPRO will obtain the Key name of the 
internal key from the source data set header, in which 
case, STOREKEYNAME must have been specified when the 
data set was enciphered. 


Abbreviation: SYSKN 
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Copy Records into a Key Sequenced Data Set: Example 1 


In this example, records from an indexed-sequential data set, 
ISAMDSET, are copied into key-~sequenced VSAM cluster, 
D40.EXAMPLE.KSDS1. 


/7REPROI JOB 
//STEPI EXEC PGM=IDCAMS 
//INDSET1 DD DSNAME=ISAMDSET, DISP=OLD, 


17 DCB=(DSORG=I1S, BUFNO=6) 
Z/SYSPRINT DD SYSOUT=A 
S/7SYSIN D x 

REPRO - 


INFILECINDSETI) - 
OUTDATASETCD40.EXAMPLE.KSD51) 
7% 


Job control language statement: 


® INDSET1 DD, which describes the indexed-~sequential data set, 
ISAMDSET, that contains the source records. The BUFNO 
parameter specifies the number of buffers assigned to the 
ISAM data set. This improves performance when the ISAM data 
set's records are accessed. 


The REPRO command copies all records from the source data set, 
ISAMDSET, to the target data set, D40.EXAMPLE.KSDS1. Its 
parameters are: 


e INFILE, which points to the INDSET1 DD statement. The 
INDSET1 DD statement identifies the source data set: 
ISAMDSET. ISAMDSET is an indexed-sequential data set. 


@ OUTDATASET, which identifies the key-~sequenced VSAM cluster 
into which the source records are to be copied. This data 
set is dynamically allocated by access method services. 
Catalog D27UCAT1 will be searched for the data set, because 
D460 is an alias for D27UCAT1. 
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Copy Records into a VSAM Data Set: Example 2 


In this two-part example, data records are copied from the 
non-~VSAM data set SEQ.D27V, a sequential data set, into a 
key-sequenced VSAM data set, DGO.MYDATA. Next, records are 
copied from the Key-~sequenced data set, DG0.MYDATA, into an 
entry~sequenced data set, ENTRY. 


//REPROZ JOB... 
// JOBCAT DD DSNAME=USERCAT3, DISP=SHR 
//STEPI EXEC PGM=IDCAMS 
S/ITNPUT DD DSNAME=SEQ.D27V, DISP=SHR, DCB=CBUFNO=6 ) 
//SYSPRINT DD SYSOUT=A 
S/7SYSIN DD % 
REPRO - 

INFILECINPUT) - 

OUTDATASETCD40 .MYDATA) 
7% 


//STEP2 EXEC PGM=IDCAMS 
//TNPUT DD DSNAME=D40 .MYDATA, DISP=OLD 
//QUTPUT DD DSNAME=ENTRY, DISP=OLD 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD ¥ 
REPRO - 
INFILECINPUT) - 
OUTFILECOUTPUT) - 
FROMKEYCDEAN) ~ 
TOKEY CJOHNSON) 
/% 


STEP1: Access method services copies records from a sequential 
data set, SEQ.D27V, into a key-~sequenced data set, DGO.MYDATA. 
STEP1's job control language statements: 


e JOBCAT BD, which makes the catalog USERCAT3 available for 
this job. 


e INPUT DD, which identifies the sequential data set, 
SEQ.D27V, that contains the source records. The BUFNO 
parameter specifies the number of buffers assigned to the 
sequential data set. This improves performance when the 
data set's records are accessed. 


STEP1's REPRO command copies all records from the source data 
set, SEQ.D27V, to the target data set, DS0.MYDATA. Its 
parameters are: 


é INFILE, which points to the INPUT DD statement. The INPUT 
DD statement identifies the source data set. 


® OUTDATASET, which identifies the key-~sequenced data set into 
which the source records are to be copied. The data set is 
dynamically allocated by access method services. 


STEP2: Access method services copies some of the records of the 
kKey~sequenced data set DG0.MYDATA into another entry~sequenced 
data set, ENTRY. STEP2's job control language statements: 


® ST EET. DD, which applies to this job step as well as to 
S i 


e INPUT DD, which identifies the key-~sequenced cluster, 
D40.MYDATA, that contains the source records. 


@ OUTPUT DD, which identifies the entry-sequenced cluster, 
ENTRY, that the records are to be copied into. 


STEP2's REPRO command copies records from the source data set, 
D440 .MYDATA, to the target data set, ENTRY. Only those records 
with key values from DEAN to, and including, JOHNSON are copied. 
The REPRO command's parameters are: 


e INFILE, which points to the INPUT DD statement. The INPUT 
DD statement identifies the source kKey-~sequenced data set. 
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e OUTFILE, which points to the OUTPUT DD statement. The 


OUTPUT DD statement identifies the entry-sequenced data set 
into which the source records are to be copied. 


e FROMKEY and TOKEY, which specify the lower and upper key 
| boundaries. Only those records with key values from DEAN 
to, and including, JOHNSON are copied. 


If ENTRY already contains records, VSAM merges the copied 
records with ENTRY's records. A subsequent job step could 
resume copying the records into ENTRY, beginning with the 
records with key greater than JOHNSON. If you subsequently 
copied records with key values less than DEAN into ENTRY, VSAM 
merges them with ENTRY's records. 
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Copy a Catalog: Example 3 


a | In this example, a catalog is copied to illustrate the catalog 
| copying procedure. 


//COPYCAT JOB sibs 
//STEPL EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//7SYSIN DD % 

DEFINE USERCATALOG - 
CNAMECCOPYUCAT) - 
MASTERPWCUCATMPW) —-— 

UDATEPNCUCATUPW) - 
FORC365) - 
VOLUMECVSERO06) ) - 
CYLINDERS(100 10) ) - 


DATA 
CCYLINDERSC20 10) ) - 


INDEX 
CCYLINDERSC10) 3 - 
CATALOG - 
CAMASTCAT/MRCATPW2) 
7X 


S/STEP2 EXEC PGM=IDCAMS 

//STEPCAT DD DSNAME=COPYUCAT, DISP=OLD 
// DD DSNAME=MYCAT, DISP=OLD 
//SYSPRINT DD SYSOUT=A 

S/SYSIN DD % 


REPRO —- 
INDATASETCMYCAT) - 
OUTDATASET CCOPYUCAT/UCATMPW) 
EXPORT - : 
MYCAT - 
DISCONNECT 
1X 
_ “/STEPS EXEC PGM=IDCAMS 
“//STEPCAT DD DSNAME=COPYUCAT , DISP=SHR 
| //SYSPRINT DD SYSOUT=A 


S/SYSIN DD x 
LISTCAT 
7% 


SSSTEPS EXEC PGM=IDCAMS 
“//STEPCAT DD DSNAME=COPYUCAT, DISP=OLD 
“/SYSPRINT DD SYSOUT=A 
S/SYSIN DD 3 
DELETE - 
MYCAT —- 
CLUSTER - 
PURGE - 
CATALOGCCOPYUCAT/UCATMPW) 
7K 


S/STEP5 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
7/7 SYSIN DD X 
DEFINE ALIAS - 
CNAMECMYCAT) - 
RELATECCOPYUCAT) ) 
7% 


STEPI1: A user catalog, COPYUCAT, is defined on volume VSERO6. 
The catalog entries in MYCAT will be copied into COPYUCAT. 


The DEFINE USERCATALOG command defines the user catalog, 
COPYUCAT. Its parameters are: 


6 NAME, which specifies the name of the new catalog, COPYUCAT. 


@ MASTERPW and UPDATEPW, which specify the master and update 
level passwords for the catalog. 


® FOR, which specifies that the catalog is to be retained for 
365 days. 
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$ VOLUME, which specifies that the catalog is to reside on 
volume VSERO6. 


e CYLINDERS, which specifies that the catalog's data space is 
initially to be 100 cylinders. When the data space is 
extended, it is to be extended in increments of 10 
cylinders. Part of the data space contains the catalog, 
COPYUCAT. The rest of the data space is available for 
suballocated VSAM data sets. 


@ DATACCYLINDERS) and INDEXCCYLINDERS) specify that the 
catalog itself is initially to occupy 30 cylinders. When 
the catalog's data component is extended, it is to be 
extended in increments of 10 cylinders. 





& CATALOG, which specifies that a user catalog connector entry 
is to be built and written into the AMASTCAT catalog. The 
user catalog connector entry points to COPYUCAT. | 


STEP2: Access method services copies the contents of MYCAT into 
COPYUCAT. 


STEP2's job control statement: 


© STEPCAT DD, which makes two catalogs available for this job 
step: COPYUCAT and MYCAT. The DD statements that identify 
the catalogs are concatenated. 


The REPRO command copies all records from MYCAT into COPYUCAT. 
Access method services treats each catalog as a key~sequenced 
data set and copies each catalog record. Consequently, the 
first 13 catalog records of MYCAT, which describe MYCAT as a 
key-sequenced data set, are also copied into COPYUCAT. Entries 
from MYCAT are written into COPYUCAT beginning with catalog 
record 14 (that is, after the 13 self-describing records of 
COPYUCAT). The REPRO command's parameters are: 


@ INDATASET, which identifies the source data set: MYCAT. 
soavuehan that MYCAT is cataloged in either MYCAT or 


@ OUTDATASET, which identifies the receiving data set: 
COPYUCAT. VSAM assumes that COPYUCAT is cataloged in either 
COPYUCAT or MYCAT. 


The EXPORT command removes MYCAT's user catalog connector entry 
from the master catalog. MYCAT's cataloged objects are now not 
available to the system. C(STEP5 builds an alias entry that 
relates MYCAT to COPYUCAT, making the cataloged objects 
available to the system again. ) 


STEPS: ‘Access method services lists the name of each entry in 
the new catalog, COPYUCAT. The STEPCAT DD statement identifies 
the catalog to be listed. 


LISTCAT cannot run in a job step where the catalog is empty when 
it is opened. To ensure that the LISTCAT correctly reflects the 
eonents of the catalog, the LISTCAT was run as a separate job 
step. 


STEP4: Access method services removes the entries in COPYUCAT 

that describe MYCAT as a kKey-sequenced data set. (See STEP2 

description above.) The DELETE command's parameters are: 

© MYCAT, which identifies the object to be deleted. 

e CLUSTER, which specifies that MYCAT is cataloged as a 
cluster in COPYUCAT. MYCAT's cluster, data, and index entry 
are removed from COPYUCAT. 


e PURGE, which specifies that MYCAT is to be deleted a 
regardless of a specified retention period or date. ae 
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e CATALOG, which specifies that MYCAT is cataloged in 
COPYUCAT. COPYUCAT’s master password, UCATMPW, is required 
to delete its catalog entries. 





STEPS: Access method services builds an alias entry that 
relates MYCAT to COPYUCAT. Because no CATALOG parameter or 
JOBCAT or STEPCAT DD statement identifies the catalog that is to 
contain the alias entry, VSAM assumes the entry is to be written 
into the master catalog. 


When MYCAT was defined, it was defined on volume VSEROG. Its 

catalog entries describe VSAM objects on that volume. COPYUCAT 

is defined on volume VSER06. Because MYCAT was copied into 

COPYUCAT Cand MYCAT no longer exists as a user catalog), 

ae aa entries now describe VSAM objects on volumes VSERO0G and 
06. 


Unload a VSAM User Catalog: Example 4 


This example shows how a VSAM user catalog can be unloaded to 
tape using the catalog unload/reload feature of the REPRO 
command. 


// UNLOAD JOB ree 

// SOBCAT DD DSNAME=D27UCAT2,DISP=OLD 

//STEPL EXEC PGM=IDCAMS 

//SYSPRINT DD SYSOUT=A 

//CATIN DD DSNAME=D27UCAT2, DISP=OLD 

//CATOUT DD DSNAME=PORTABLE.TAPE,LABEL=C€1,SL), 


// DISP=NEW, UNIT=TAPE,VOL=SER=TAPEOIL, 
Sf DCB=(DEN=3,RECFM=VB, LRECL=516, BLKSIZE=5164) 
“/SYSIN DD x 
REPRO - 
INFILECCATIN/USERMRPH) - 


OUTFILECCATOUT >) 


(_ /¥® 


Job control language statements: 


e JOBCAT DD, which is required, and which identifies and 
allocates the user catalog as the job catalog. 


° CATIN DD, which describes and allocates the user catalog, 
D27UCAT2, as a VSAM data set to be opened and used by the 
REPRO command as the source data set for the unload 
operation. 


® CATOUT DD, which describes and allocates a magnetic tape 
file to contain the copy of the catalog. The DCB parameters 
must be specified as shown. The BLKSIZE parameter can be 
any multiple of LRECL plus 4, where LRECL=516. 


The REPRO command causes the VSAM user catalog D27UCAT2 to be 
unloaded (that is, copied) to a magnetic tape file. The REPRO 
command's parameters are: 


e INFILE, which is required, and which identifies the user 
catalog as a source VSAM data set. The catalog's master 
password is required to open it as a data set. 


e OUTFILE, which is required, and which describes the magnetic 
tape file, or target data set that is to contain the 
catalog's copy. 
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Reload an Unleaded VSAM User Catalog: Example 5 


This example shows how a VSAM user catalog can be reloaded from 


the backup copy, created in the previous example, using the 
catalog unload/reload feature of the REPRO command. 


//RELOAD JOB ied 
47 SOBCAT DD DSNAME=D27UCAT2, DISP=OLD 
//STEPI EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//CATIN DD DSNAME=PORTABLE.TAPE,LABEL=(1,5L), 
// DISP=OLD,UNIT=TAPE, VOL=SER=TAPEO1 , DCB=DEN=3 
//CATOUT DD DSNAME=D27UCATZ, DISP=GLD 
//SYSIN DD X | 
REPRO. - 
INFILECCATIN) - 
OUTFILECCATOUT/USERMRPW) 
1% 


Job control language statements: 


e JOBCAT DD, which is required and which describes and 
allocates the user catalog to be reloaded. The JOBCAT 
statement specifies that D27UCAT2 is the job catalog. 


e CATIN DD, which describes and allocates the magnetic tape 
file that contains the unloaded copy of the catalog. 
Because a standard label tape is used, DCB parameters of 
record format, record size, and block size need not be 


specified. For a nonlabeled tape, the same parameters as in 


the previous example must be specified. 


e CATOUT DD, which describes the user catalog as a VSAM data 


set to be opened and used by REPRO as the target data set 
for the reload operation. 


The REPRO command causes a VSAM user catalog to be reloaded from 


the backup copy created in the previous example. The REPRO 
command's parameters are: | 


® INFILE, which is required, and which identifies the magnetic 
tape file that contains the unloaded, or backup, copy of the 


user catalog. 


e OUTFILE, which is required and which identifies the user 
catalog as a VSAM data set to be opened for record 


processing. The master password allows opening the catalog 


as a data set. 


Encipher Using System Keys: Example 6 


In this example, an enciphered copy of part of a VSAM relative 


record data set is produced using a tape as output. The 
enciphered data set is to be deciphered at a remote 


installation. Four source records at a time will be enciphered 


as a unit. The Keys will be managed by the IBM Programmed 
Cryptographic Facility or the IBM Cryptographic Unit Support. 
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/7ENSYS JOB cats | 
//JSOBCAT DSN=D27UCAT, DISP=SHR 
//STEPI EXEC PGM=IDCAMS 
//CLEAR DD DSN=RRDS1, DISP=SHR 
S/7CRYPT DD DSN=RRDSEN, LABEL=(1,SL),DISP=NEW 
UNIT=TAPE, VOL=SER= TAPEOI, 
DCB=( DEN=3, RECFM=FB, LRECL= 516,BLKSIZE=5160) 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD X% 
REPRO - 
INFILECCLEAR/RDPW) - 
OUTFILECCRYPT) - 
COUNTC50) - 
ENCIPHER - 
CEXTERNALKEYNAMECAKEY27) - 
STOREDATAKEY - 
CIPHERUNITCG) - 
USERDATACCONF)) 


— 
o 


/X% 
Job control language statements: 
e JOBCAT DD makes the catalog D27UCAT available. 
° CLEAR DD describes the relative record data set. 


e CRYPT DD describes and allocates a magnetic tape file. 
LRECL is the relative record data set record size plus 4. 


The REPRO command copies 50 records enciphered from a generated 
data encrypting key, from the source data set, RRDSI1, to the 
output tape. The source records will be enciphered in units of 
four records, except for the last two records, which will be 
enciphered together. The enciphered data encrypting key will be 
stored in the header of the target data set; therefore, REPRO 
will not list the key name or enciphered data encrypting key in 
SYSPRINT. The parameters of the REPRO command are: 


e INFILE points to the CLEAR DD statement, identifying the 
source data set to be enciphered, RRDS1. RRDS1 is cataloged 
in either D27UCAT or the master catalog. The read password 
for the source data set is RDPH. 


e OUTFILE points to the CRYPT DD statement, identifying the 
target data set on tape. 


® COUNT indicates the copy operation is to end after 50 
records have been copied. 


6 ENCIPHER indicates that the target data set is to contain an 
enciphered copy of the source data set. 


e EXTERNALKEYNAME supplies the name, AKEY27, of the external 
file key to be used to encipher the data encrypting key. 


6 STOREDATAKEY indicates that the data encrypting key 
enciphered under the secondary file key is to be stored in 
the header of the target data set. 


e CIPHERUNIT indicates that 4 source records at a time are to 
be enciphered as a unit. 


e USERDATA specifies a character string, "CONF", to be stored 
in the header of the target data set as user data. 
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Decipher Using System Keys: Example 7 


In this example, the enciphered data set produced by the job in 
Example 6 is deciphered at the remote location, using a VSAM 
relative record data set as the target for the plaintext 
(deciphered) data. The empty slots in the original data set 
will be reestablished. Keys will be managed by the IBM 
Programmed Cryptographic Facility or the IBM Cryptographic 
Support Unit. 


//DESYS JOB oe 

4/JOBCAT DSN=D27UCATR, DISP=SHR 

S/STEP2 EXEC PGM=IDCAMS 

S/CRYPT DD DSN=RRDSEN, LABEL=(1,5L),DISP=OLD, 
UNIT=TAPE,VOL=SER=TAPEOI, 
DCB=DEN=3 

//CLEAR DD DSN=RRDS2, DISP=SHR 

“/SYSPRINT DD SYSOUT=A 

//SYSIN DD Xx . 


INFILECCRYPT) - 
OUTFILECCLEAR/UPPW2) - 
DECIPHER ~- 
CSYSTEMKEY - 
SYSTEMKEYNAMEC BKEY27 )) 





wo 
oO 


7% 


Job control language statements: 
e JOBCAT DD makes the catalog D27UCATR available. 


@ CRYPT DD describes and allocates the magnetic tape 
containing the enciphered data. 


e CLEAR DD describes the relative record data set. 


The REPRO command copies and deciphers the enciphered data set | 
from the source tape to the target data set RRDS2. The iv 
enciphered data encrypting key is obtained from the header of 

the source data set. The internal file key (BKEY27) is used to 
decipher the enciphered data encrypting key, which is then used 

to decipher the data. The parameters of the REPRO command are: 


° INFILE points to the CRYPT DD statement, identifying the 
tape containing the enciphered source data. 


e OUTFILE points to the CLEAR DD statement, identifying the 
data set to contain the deciphered data, RRDS2. RRDS2 is 
cataloged in either D27UCATR or the master catalog. The 
defined record size must be the same as that of the original 
relative record data set. The update password for the 
target data set is UPPW2. 


® DECIPHER indicates that the source data set is to be 
deciphered as it is copied to the target data set. 


6 SYSTEMKEY indicates that Keys are to be managed by the IBM 
ited Cryptographic Facility or the IBM Cryptographic Unit 
upport. 


e SYSTEMKEYNAME supplies the key name, BKEY27, of the internal 
file key that was used to encipher the system data 
encrypting key. The file Key must be an internal file key 
in this system. 


eeleeeet 
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Encipher Using Private Keys: Example 8 


In this example, an enciphered copy of a SAM data set is 
produced by uSing an entry~sequenced data set as the target data 
set. The enciphered data set resides on a volume that is to be 
stored offline at the local installation. Each record in the 
target data set will be enciphered separately, using a data 
encrypting key supplied by the user via a data encrypting Key 
data set. Keys will be managed privately by the user. 


//7ENPRI JOB alec 
//SOBCAT DD DSN=D27UCAT, DISP=SHR 
//STEPI EXEC PGM=IDCAMS 
//CLEAR DD DSN=SAMDS1,DISP=OLD, 
VOL=SER=VOL005,UNIT=DISK 

77CRYPT DD DSN=ESDS1, DISP=OLD 
//KEYIN DD 3 

53467568503A7C29 
7% 


//SYSPRINT DD SYSOUT=A 
S/SYSIN DD ¥ 
REPRO - 
INFILECCLEAR) - 
OUTFILECCRYPT/UPPW) - 
REUSE - 
ENCIPHER - 
CPRIVATEKEY - 
DATAKEYFILECKEYIN)) 
7% 


Job control language statements: 

e JOBCAT DD makes the catalog D27UCAT available. 

¢ CLEAR DD describes the SAM data set. 

e CRYPT DD describes the entry-sequenced data set. 


e KEYIN DD describes the data encrypting key data set 
ee of a single record containing the data encrypting 
ey. 


The REPRO command copies all records enciphered under the 
supplied data encrypting key, from the source data set, SAMDSI, 
to the target data set, ESDS1. The plaintext private data 
encrypting keys will not be listed on SYSPRINT, because the user 
manages the key. The parameters of the REPRO command are: 


e INFILE points to the CLEAR DD statement, identifying the 
source data set to be enciphered, SAMDS1. 


e OUTFILE points to the CRYPT DD statement, identifying the 
target data set, ESDS1. ESDS1] is cataloged in either 
D27UCAT or the master catalog. The defined maximum record 
size of the entry-sequenced data set must be large enough to 
accommodate the largest SAM record. 


e REUSE indicates that the target data set is to be opened as 
a reusable data set. If the data set was defined as REUSE, 
it is reset to empty; otherwise, the REPRO command will 
terminate. 


@ ENCIPHER indicates that the target data set is to contain an 
enciphered copy of the source data set. 


@ PRIVATEKEY indicates that the key is to be managed by the 
user. 


e DATAKEYFILE points to the KEYIN DD statement, which supplies 


the plaintext data encrypting Key, X'53467568503A7C29', to 
be used to encipher the data. 
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Decipher Using Private Keys: Example 9 


In this example, the enciphered data set produced by the job in 
Example 8, is deciphered at the same location, using an 
entry-sequenced data set as the target for the plaintext 
Cdeciphered) data. Keys will be managed privately by the user. 


//DEPRI JOB ns 
//SOBCAT DD DSN=D27UCAT, DISP=SHR 
//STEPI EXEC PGM=IDCAMS 
7/CRYPT DD DSN=ESDS1,DISP=OLD 
//CLEAR DD DSN=ESD53,DISP=OLD 
//SYSPRINT DD SYSOUT=A 
“/SYSIN DD xX 
REPRO - 
INFILECCRYPT/RDPW1) - 
OUTFILECCLEAR/UPPW3) - 
DECIPHER - 
CDATAKEYVALUECX'53467568503A7C29'") ) 
1% 


Job control language statements: 
e JOBCAT DD makes the catalog D27UCAT available. 


° CRYPT DD describes the enciphered source entry-~sequenced 
data set. 


e CLEAR DD describes the target entry~sequenced data set. 


The REPRO command copies and deciphers the enciphered data set 
from the source data set, ESDSI], to the target data set, ESDS3. 
The supplied plaintext data encrypting key is used to decipher 
the data. The parameters of the REPRO command are: 


e INFILE points to the CRYPT DD statement, identifying the 
source data set to be enciphered, ESDS1. ESDS]1 is cataloged 
in either D27UCAT or the master catalog. The read password 
for the source data set is RDPW1. 


e OUTFILE points to the CLEAR DD statement, identifying the 
target data set, ESDS3. ESDS3 is cataloged in either 
D27UCAT or the master catalog, and must be empty. The 
defined maximum record size of the target entry~sequenced 
data set must be large enough to accommodate the largest 
source entry-sequenced data set record. The update password 
for the target data set is UPPNWS3 


e DECIPHER indicates that the source data set is to be 
deciphered as it is copied to the target data set. 


° DATAKEYVALUE indicates that Keys are to be managed by the 
user, and supplies the plaintext private data encrypting 
pat X'53467568503A7C29!, which was used to encipher the 
data. 
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RESETCAT 


The RESETCAT command compares catalog entries with catalog 
recovery area (CRA) entries in order to regain access to ale 
data. This command is for use with re 7 Cc Logs 


The format of the RESETCAT command is: 





RESETCAT] CATALOG(catnamel ‘password! ddnamel) 
TCRAFTLES( (ddnamel f ALL| NONE]) 
[(ddnamelf ALL] NONEI)...1)] 
CRAVOLUMES((volserl[ devtypel) 


[(volserf devtypel)...1)} 
[IGNORE | NOIGNORE] 
[MASTERPW( password)] 
[WORKCAT( catnamel /password1)1 
[WORKFILE(ddnamel[/password])] 





RESETCAT may be abbreviated: RCAT. 


RESETCAT PARAMETERS 


Required Parameters 
CATALOG ( catnamel “password1{ddname!) 


identifies the catalog to be reset. The catalog specified 
by catname must have the RECOVERABLE attribute. 


Exclusive control of the catalog is required throughout the 
duration of the command. Also, no VSAM data sets cataloged 
m in the catalog may be open. The master catalog may not be 
( reset while it 1S in use as a master catalog. 


password 
specifies the catalog's master password. If the 
catalog is password protected, you must specify the 
master password of the catalog. RACF: The alter RACF 
authority to the catalog 1s required. 


specifies the name of the DD statement for the catalog 
being reset. If ddname is not specified, the catalog 
will be dynamically allocated. ddname must also be 
specified in a JOBCAT or STEPCAT. 


Abbreviation: CAT 


CRAFILES((ddnamel£ ALL] NONE] )...) 
specifies a list of DD statements that identify the volumes 
and devices to be used to reset the catalog. Each volume 
contains a CRA that has a copy of the catalog records 
describing the VSAM objects on that volume. ALL Specifies 
that the catalog records in the CRA on the volume specified 
by ddnamel are to be reset. 


If a volume contains a multivolume data set whose catalog 
entry is being reset, other volumes of that multivolume 
data set may be needed during the reset operation; you 
should specify these via additional ddnamel parameters. 

Use the NONE subparameter if you do not want the entries in 
these additional volumes to be used to reset the catalog. 


If a volume is needed and you do not specify the DD 
statements provided by CRAFILES, it will be allocated 
. c dynamically, and will assume the NONE attribute. 


CRAVOLUMES((volser[ devtypel)...) 
specifies the volume serial numbers and corresponding 
device types of the volumes used in resetting the catalog. 
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Each volume contains a catalog recovery area (CRA) that has 
a copy of the catalog records that describe the objects on 
the volume. The volume is allocated dynamically. 


specifies the volume serial number used in resetting 
the catalog. 


specifies the device type for the associated volser. 
If you do not specify devtype, the volume must be 
mounted and on a unit marked permanently resident or 
reserved. If you specify a generic name for devtype, 
the volume need not be mounted. 


| If a volume contains a multivolume data set whose 

| catalog entry is being reset, other volumes of that 
| multivolume data set may be needed during the reset 
| operation; if needed and not specified for reset, 
these volumes will be allocated dynamically. 
Dynamically allocated volumes assume the NONE 
attribute as described for the CRAFILES parameter. 


Abbreviation: CRAVOL 


Optional Parameters 
IGNORE | NOTGNORE 


specifies whether RESETCAT should continue processing and 
force the reset when certain errors are encountered. These 
errors may be: 


e I/0 error in the catalog. 
® I/0 error in the CRA. 


e The volume record or its extensions in the CRA are in 
error. 


IGNORE 
specifies that the RESETCAT command will try to 
recover as much information as possible and reset the 
catalog's description of those data sets on the 
specified volumes. 


For example, if IGNORE is specified and an I/O error 
occurs while processing a record from a CRA, that 
record will be ignored. In the process, data sets 
that could not be recovered on a particular volume 
would be marked unusable on that volume, and the space 
that was assigned to them would be freed. 


Abbreviation: IGN 


NOIGNORE 
specifies that I/0 errors result in immediate 
termination. 
Abbreviation: NIGN 
MASTERPW( password) 


specifies the master catalog's master password when the 
master catalog is password protected. 


WORKCAT(catnamel/ 1) 
specifies the name of the catalog in which RESETCAT defines 
the WORKFILE. This catalog must not be the same as the 
catalog being reset. The catalog must be specified ina 
JOBCAT or STEPCAT DD statement. 


If you do not specify the WORKCAT parameter, the catalog 


will be chosen using existing rules for "Order of Catalog 
Selection for DEFINE™ on page 16 


248 MVS/XA VSAM Catalog: Access Method Services Reference 








oN 
eed 











RESETCAT 


If you do not specify the WORKCAT parameter, the catalog 
must be the first DD statement in the JOBCAT or STEPCAT DD 
statement concatenation. However, if the work file catalog 
is the master catalog, then you must specify the WORKCAT 
parameter and it must be the last DD statement in the 
JOBCAT or STEPCAT DD statement concatenation. The 
eo catalog must not be the same as the one being 
reset. 


If the catalog is password protected, the update- or 
higher-level password is required. RACF: The update 
or higher RACF authority to the catalog is required. 


Abbreviation: WCAT 


WORKFILE( ddnamel/password]) 


specifies the name of a DD statement that identifies a VSAM 
data set name and a list of volume serial numbers of 
volumes containing VSAM data spaces and units to be used by 
RESETCAT for a work file. These volumes must be owned by 
the catalog in which the work file is defined. 


This data set will be defined by RESETCAT and used as 
temporary storage while processing the command; it will be 
deleted at the end of the command. The data set must not 
be already defined. 


Space requirements for the data set are noted in “"WORKFILE 

Space Requirements" in Catalog Administration Guide. If 

he do not specify WORKFILE, IDCUT1 is used as a default 
name. 


If you require one, you may specify a password to be 
used by RESETCAT to password protect the work file. 
Because the work file will contain a copy of the 
catalog records, it may contain security-sensitive 
information. The password you specify will become the 
work file's master password. You may specify the 
password only if ddname is explicitly specified. 


Abbreviation: WFILE 
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RESETCAT EXAMPLES 


Resetting a Catalog: Example 1 


This example illustrates the use of RESETCAT to reset a catalog 
CUSERCAT1), one of whose owned volumes (VSERO1) has been 
restored. The other volume owned by USERCATI1 is VSEROZ. 


//RECOVER JOB... 
//STEPI EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//STEPCAT DD  DSN=USERCAT1, DISP=OLD 
11 DD DSN=AMASTCAT, DISP=OLD 
//IDCUT1 DD  DSN=WORKFILE,DISP=OLD, | 
Ve, VOL=SER=333333,UNIT=DISK, AMP=" AMORG® 
//CRAVOL1 DD DISP=OLD,VOL=SER=VSERO1,UNIT=DISK 
//CRAVOL2 DD  DISP=OLD,VOL=SER=VSERO2,UNIT=DISK 
//DDCAT DD DSN=USERCATI, DISP=OLD 
//SYSIN DD x 
RESETCAT - | 
CATALOGCUSERCATI1/MASTER DDCAT) - 
CRAFILESC((CRAVOLI1 ALL) CCRAVOL2 NONE)) - 
WORKCATCAMASTCAT/MCATMRPH) - 
MASTERPN(MCATMRPH) - 
IGNORE 
7% 


Job control language statements: 


6 STEPCAT DD, which makes the user catalog, USERCAT1, and the 
master catalog, AMASTCAT, available for the step. These 
catalogs must be available for the catalog to be reset and 
for the work file to be defined, respectively. Note that, 
when the work file is to be defined in the master catalog, 
the master catalog must be last in the concatenation and the 
catalog name is supplied via the WORKCAT parameter. 


e IDCUT1] DD, which identifies the data set to be used for the 
work file. | 


cd 


e CRAVOL1 DD, which identifies and allocates a volume whose 
catalog recovery area is to be used to reset the catalog. 


e CRAVOL2 DD, which identifies and allocates a volume whose 
catalog recovery area may change as a result of resetting 
the catalog recovery area on volume VSERO]. This volume is 
not reset in the catalog. 


& DDCAT DD, which allocates the catalog to be reset. 


The RESETCAT command causes catalog USERCAT1] to be reset from 
the catalog recovery area on VSERO1L. The RESETCAT command's 
parameters are: 


@ CATALOG, which identifies the catalog to be reset. The 
master password of the catalog is required to update the 
catalog. The DD statement for the catalog is also 
identified. 


® CRAFILES, which specifies a list of DD statements that 
identify the volumes to be used to reset the catalog. ALL 
specifies that the catalog records in the CRA on the volume 
specified by the CRAVOL1 DD statement are to be reset Cin 
the catalog). NONE allows the CRAVOL2 DD statement to be 
specified for a CRA volume that is not to be used for reset, 
but that may be needed as a result of the reset (for 
example, a multivolume data set resides on a reset volume 
and on a nonreset volume). ° a 


e WORKCAT, which specifies the name of the catalog in which to “a” 


define the work file. WORKCAT must be specified if the work 
file is to be defined in the master catalog. 
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e IGNORE, which specifies that RESETCAT should force the reset 
of the catalog despite certain errors that may be 
encountered during the RESETCAT processing. 


Resetting a Catalog: Example 2 


This example illustrates the use of RESETCAT to reset a catalog 
CUSERCAT1) after the volume (VSERO0O0) on which the catalog 
resides has been restored. The volumes owned by USERCATI, 
VSERO1, and VSERO2 have been determined to be out of 
synchronization with the catalog by running a LISTCRA with the 
COMPARE option for all volumes owned by USERCAT1. 


7/RECOVER JOB... 

7/7 JOBCAT DD DSN=USERCAT2, DISP=OLD 

if DD DSN=USERCAT1, DISP=OLD 

//STEPI1 EXEC PGM=IDCAMS 

“/SYSPRINT DD SYSOUT=A 

//WORKF DD DSN=WORKFILE, DISP=OLD,UNIT=CDISK, 2), 








// VOL=SER=(333333,333334),AMP="AMORG! 
S/SYSIN DD 53 
RESETCAT —- 
CATALOGCUSERCATI) - 
CRAVOLSCCVSERO] 3330-1ICVSERO2 3330-129) - 
WORKFILECWORKF/WRKPSW) - 


NOIGNORE 
7% 


Job control language statements: 


8 JOBCAT DD, which makes the user catalogs USERCAT2 and 
USERCAT1] available for the job. These catalogs must be 
available for the work file to be defined and for the 
catalog to be reset, respectively. 


@ WORKF DD, which identifies the data set to be used for the 
work file. 


Note: All other required volumes will be dynamically 
allocated by RESETCAT. 


The RESETCAT command causes catalog USERCAT1 to be reset from 
the catalog recovery areas on VSERO1 and VSERO2. The RESETCAT 
parameters are: 


¢ CATALOG, which identifies the catalog to be reset. 


° CRAVOLS, which specifies a list of volumes and their device 
types to be used to reset the catalog. 


e WORKFILE, which specifies the DD statement for the work file 
and a password to be used as the work file's master 
password. 


@ NOIGNORE, which specifies that RESETCAT should not force the 
reset of the catalog if certain errors are encountered. 
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Resetting a Catalog: Example 3 


This three part example illustrates the use of RESETCAT to reset 
a catalog CUSERCAT1 on volume VSERO0) that must be reallocated 
on a different volume (VSERO3). Such a situation may occur when 
irreparable physical damage has occurred to the catalog. In 
this example, the catalog recovery area for the damaged catalog 
volume is assumed to be accessible and valid and thus included 
for reset in the newly defined catalog. Note that the newly 
defined catalog bears the same name as the damaged catalog. The 
other volumes owned by USERCAT1 are VSERO1] and VSERO2. The 
catalog is first disconnected, then redefined. 


//DISC JOB... 
//STEPI EXEC PGM=IDCAMS 
“/SYSPRINT DD SYSOUT=A 
//STEPCAT DD DSN=USERCAT1, DISP=0LD 
S/SYSIN DD xX 

EXPORT USERCAT1 DISCONNECT 


//STEP2 EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
//UCATDD DD VOL=SER=VSER03,UNIT=DISK, DISP=OLD 
//CRAVOL1 DD VOL=SER=VSERO1,UNIT=DISK, DISP=OLD 
//CRAVOL2 DD VOL=SER=VSER0O2,UNIT=DISK, DISP=OLD 
“7SYSIN DD * 
DEFINE UCAT - 

CNAME CUSERCAT1) FILECUCATDD) VOLCVSEROS) - 

RECOVERABLE CYL(€20 1)) - 

DATACCYL(10 13) INDEXC(CYL(€1)) 


//STEPS EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
“/STEPCAT DD DSN=USERCAT1, DISP=OLD 
17 DD DSN=AMASTCAT, DISP=OLD 
//IDCUTI DD DSN=WORKFILE, DISP=OLD,UNIT=DISK, 
4/ VOL=SER=333333,AMP="AMORG* 
“/SYSIN DD % 
RESETCAT - 

CATALOGCUSERCAT1) - 

WORKCATCAMASTCAT) —- 

CRAVOLSCCVSEROO 33350) (VSERO] 3350-LICVSERO2 3330-1)) 
7% 


STEP1: The user catalog, USERCAT1, is disconnected from the 
system by using the EXPORT command. 


at The user catalog, USERCAT1, is redefined on the volume 
$ , 


STEP3: The user catalog USERCAT1 is reset from the previous 
catalog's owned volumes. 


Job control language statements: 


@ STEPCAT DD, which makes the user catalog, USERCAT1, and the 
master catalog, AMASTCAT, available for the step. These 
catalogs must be available for the catalog to be reset, and 
for the work file to be defined, respectively. 


® IDCUT1 DD, which identifies the data set to be used for the 
work file. 
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The RESETCAT command causes the redefined catalog USERCAT1 to be 
reset from the catalog recovery areas on volumes VSERO0, VSEROI, 
and VSERO2. The RESETCAT command's parameters are: 
@ CATALOG, which identifies the catalog to be reset. 
® WORKCAT, which specifies the name of the catalog in which to 
define the work file. WORKCAT must be specified if the work 
file is to be defined in the master catalog. 


@ CRAVOLS, which specifies a list of volumes and their device 
types to be used to reset the catalog. 
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The VERIFY command causes a catalog to correctly reflect the end 
of a data set after an error has occurred while closing a VSAM 
data separ The error may have caused the catalog to be 
incorrect. 


The format of the VERIFY command is: 


VERIFY PARAMETERS 


Required Parameters 


VERIFY LFILE(ddnamel/password])| 
DATASET (entrynamel/password] )} 


VERIFY can be abbreviated: VFY 


FILE(ddnamel/password] ) 
ddname specifies the name of a DD statement that identifies 
the cluster or alternate index to be verified. For further 
information, see "Using VERIFY to Synchronize Values™ in 


is the control or master password of a 
password-protected object CRACF: The control or alter 
RACF authority to the object is required), or is the 
master password of the object's password-protected 
catalog CRACF: The alter RACF authority to the 
catalog is required). 


DATASET lentrynamel[/password]) 
specifies the name and password of the object to be 
Aria If DATASET is coded, the object is dynamically 
allocated. 


Ww 
is the control or master password of a 
password-protected object CRACF: The control or alter 
RACF authority to the object is required), or is the 
master password of the object's password-protected 
catalog CRACF: The alter RACF authority to the 
catalog is required). 


Abbreviation: DS 


The VERIFY command can be used following a system failure that 
caused a component opened for update processing to be improperly 
closed. It can also be used to verify an entry-~sequenced data 
set defined with REUSE that was open in create mode when the 
system failure occurred. 


Note: When sharing data sets between different processors, it 
is recommended that you run VERIFY as the first step of a job 
stream to prevent job termination caused by an open ACB error 
code, if the other processor already has the data set open. 
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VERIFY 
VERIFY EXAMPLE 


Upgrading a Data Set's End-of-File Information: Example 


When a data set that was improperly closed (that is, closed as a 
result of system failure) is opened, the VSAM OPEN routines set 
a return code to indicate that the data set's cataloged 
information might not be accurate. The user can upgrade the end 
of data CEOD) and end of Key range CEOKR) information Cso that 
it is accurate when the data set is next opened) by closing the 
data set! and issuing the VERIFY command: 


//NERIFY JOB... 
//IJOBCAT DD DSNAME=D27UCATI, DISP=SHR 
//FIXEOD EXEC PGM=IDCAMS 
//SYSPRINT DD SYSOUT=A 
SSSYSIN DD % 
LISTCAT A eens = 


VERIFY DATASET CFAROUT) 
LISTCAT i ee = 


7% 


The first LISTCAT command lists the data set's cataloged 
information, showing the data set's parameters as they were when 
the data set was last closed properly. 


The VERIFY command updates the data set's cataloged information 
to show the data set's real EOD and EOKR values. 


The second LISTCAT command lists the data set's cataloged 
information again. This time, the EOD and EOKR information show 
the point at which processing stopped due to system failure. 
This information should help the user determine how much data 
was added correctly before the system failed. 


Note: VERIFY will only update the high-~used RBA fields for the 
data set, and not any record counts. 


See Appendix A, “Interpreting LISTCAT Output Listings™ on 
page 256, for details on the order in which catalog records are 
to be listed and the meanings of the listed records. 


1 When the data set is opened (first OPEN after system 
failure), VSAM OPEN sets a "data set improperly closed" 
return code. When the data set is closed properly, VSAM 
CLOSE resets the "data set improperly closed" indicator but 
does not upgrade erroneous catalog information that resulted 
from the system failure. Subsequently, when the data set is 
next opened, its EOD and EOKR information might still be 
erroneous Cuntil VERIFY is issued to correct it), but VSAM 
OPEN sets the "data set opened correctly™ return code. 
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The various LISTCAT command options allow you to select the 
LISTCAT output that gives you the information you want. This 
appendix provides information on the structure of LISTCAT output 
when you specify certain options. It also lists and describes 
fields that can be printed for each type of catalog entry. 


Each listed entry is identified by its type (that is, cluster, 
non-VSAM, data, and so forth) and by its entryname. Entries are 
listed in alphabetic order of the entrynames, except when the 
ENTRIES parameter is used. The entries are then listed in the 
order in which they are specified in the ENTRIES parameter. 


An entry that has associated entries is immediately followed by 
the listing of each associated entry. That is, a cluster's data 
component Cand, if the cluster is key~sequenced, its index 
component) is listed immediately following the cluster. If type 
options CCLUSTER, DATA, SPACE, etc.) have been specified or a 
generic entryname list was specified, this excludes the 
associated entry. 


This appendix 1S organized in three parts: 


e "LISTCAT Output Keywords™ lists all field names that can i 
listed for each type of entry. 


@ "Description of Keyword Fields™ describes each field name 
within a group of related field names. 


e "Examples of LISTCAT Output Listings" describes and 
illustrates the LISTCAT output that results when various 
LISTCAT options are specified. 


LISTCAT OUTPUT KEYWORDS 


This section lists the field names associated with each type of 
catalog entry. Each field name is followed by an abbreviation 
that points to a group of related field descriptions in the next 
section. Keywords are listed in alphabetic order, not in the 
order of appearance in the LISTCAT output. 


The group names and abbreviations are: 


Abbreviations Group Names 


ALC allocation group 

ASN associations group 

ATT attributes group 

DSP data space group 

GDG generation data group base entry, special fields 
NVS non-VSAM entry, special field 

HIS history group 
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Abbreviations Group Names 





PRT protection group 
= STA statistics group 
VLS volumes group 
VOL volume entry, special fields 


Alias Entry Keywords 


ASSOCIATIONS (ASN) 

entryname (HIS) 

HISTORY (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 


Alternate~-Index Entry Keywords 


ASSOCIATIONS CASN) 
ATTEMPTS (PRT) 
ATTRIBUTES CATT) 
CLUSTER CASN) 
CODE (PRT) 
CONTROLPW (PRT) 
DATA CASN) 
entryname (HIS) 
HISTORY CHIS) 
CREATION (HIS) 
EXPTRATION (HIS) 
ie. OWNER=IDENTCHIS) 
a RCVY-CI (CHIS) 
| RCVY=DEVT (HIS) 
RCVY-VOL CHIS) 
RELEASE (HIS) 
INDEX (ASN) 
MASTERPW (PRT) 
NOUPGRADE (CATT) 
PATH CASN) 
PROTECTION (PRT) 
RACF (PRT) 
READPW (PRT) 
UPDATEPW (PRT) 
UPGRADE (ATT) 
USAR (PRT) 
USVR (PRT) 


Cluster Entry Keywords 


AIX (ASN) 
ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 
CODE (PRT) 
CONTROLPW (PRT) 
DATA (ASN) 
entryname (CHIS) 
HISTORY (HIS) 
CREATION (CHIS). 
EXPIRATION (HIS) 
OWNER=-IDENT CHIS) 
RCVY-CI (CHIS) 
RCVY=-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
INDEX (ASN) 
MASTERPW (PRT) 
PATH (ASN) 
PROTECTION (PRT) 
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Data Entry Keywords 


entryname 
ERASE (ATT) 











RACF (PRT) 
READPW (PRT) 
UPDATEPW (PRT) 
USAR (PRT) 
USVR (PRT) 


ALLOCATION (CALC) 
AIX (ASN) 
ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 
ATTRIBUTES (ATT) 
AVGLRECL (ATT) 
AXRKP CATT) 

BIND (ATT) 
BUFSPACE CATT} 
BYTES/TRACK (VLS) 
CI/CA (ATT) 
CISIZE (ATT) 
CLUSTER (CASN) 
CODE (PRT) 
CONTROLPW (PRT) 
CYLFAULT (CATT) 
DEVTYPE ({VLS) 
DSTGWAIT CATT) 
(HIS) 


EXCPEXIT (ATT) 
EXCPS (STA) 
EXTENT-NUMBER (VLS} 
EXTENT~TYPE (CVLS) 
EXTENTS (STA) 
EXTENTS (VLS) 
HIGH-CCHH [(VLS) 
HIGH-RBA (VLS) 
LOW-CCHH (VLS) 
LOW-RBA (VLS) 
TRACKS (VLS) 
FREESPACE-%CI (STA) 
FREESPACE~%CA (STA) 
FREESPC-BYTES (STA) 
HIGH-KEY (VLS) 
HI-KEY-RBA (VLS) 
HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION CHIS) 
OWNER-IDENT CHIS) 
RCVY-CI (HIS) 
RCVY-DEVT CHIS) 
RCVY-VOL (HIS) 
RELEASE CHIS) 
IMBED CATT} 
INDEX (ASN) 
INH-UPDATE CATT) 
INDEXED (ATT) 
KEYLEN (CATT) 
LOW-KEY (VLS) 
MASTERPW (PRT) 
MAXLRECL (ATT) 
MAXRECS CATT) 
NOERASE CATT} 
NOIMBED (CATT) 
NONINDEXED CATT} 
NOREPLICAT (ATT) 
NOREUSE (CATT) 
NONSPANNED (ATT) 
NOSWAP (CATT) 
NOTRKOVFL CATT) 
NONUNIQKEY (ATT) 
NOTUSABLE (ATT) 
NOWRITECHK CATT) 
NUMBERED (ATT) 
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ORDERED (CATT) 

. PGSPC (ASN) 

po PHYRECS/TRK (VLS) 

PHYREC/SIZE (VLS) 
PROTECTION (PRT) 
RACF (PRT) 
HI-ALLOC-RBA CALC) 
HI-USED-RBA (ALC) 
HI-ALLOC-RBA (VLS) 
HI-USED-RBA (VLS) 
READPW (PRT) 
RECOVERY (ATT) 
REC-DELETED (STA) 
REC-INSERTED (STA) 
REC-RETRIEVED (STA) 
REC=-TOTAL (STA) 
REC-UPDATED (STA) 
RECORDS/CI (ATT) 
REPLICATE (ATT) 
RKP (ATT) 
REUSE (ATT) 
RECVABLE (ATT) 
SHROPTNS (ATT) 
SPACE~PRI (CALC) 
SPACE~SEC (ALC) 
SPACE~TYPE (ALC) 
SPEED (ATT) 
SPLITS-CA (STA) 
SPLITS-CI (STA) 
SPANNED (ATT) 
STATISTICS (STA) 
SUBALLOC (CATT) 
SWAP (ATT) 
SYSTEM-TIMESTAMP (STA) 
TEMP-EXP (ATT) 

- TRACKS/CA (VLS) 

_ TRKOVFL (CATT) 

( UNORDERED (ATT) 
UNIQUE (ATT) 
UNIQUEKEY (ATT) 
UPDATEPW (PRT) 
USAR (PRT) 
USVR (PRT) 
VOLFLAG (VLS) 
VOLSER (VLS) 
VOLUMES (VLS) 
WRITECHECK (ATT) 


Index Entry Keywords 


ALLOCATION (ALC) 
AIX (ASN) 
ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 
ATTRIBUTES (CATT) 
AVGLRECL (ATT) 
BIND (ATT) 
BUFSPACE (ATT) 
CI/CA (ATT) 
CISIZE (ATT) 
CLUSTER (ASN) 
CODE (PRT) 
CONTROLPW (PRT) 
CYLFAULT CATT) 
DEVTYPE (VLS) 
DSTGWAIT (ATT) 

a (HIS) 
ERASE (CATT) 
EXCPEXIT (ATT) 
EXTENTS (STA) 
EXTENT-NUMBER (VLS) 
EXTENT-TYPE (VLS)} 
EXTENTS (VLS) 
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HIGH-CCHH (VLS) 
HIGH-RBA (VLS) 
LOW-CCHH (VLS) 
LOW-RBA (VLS) 
TRACKS (VLS) 

FREESPACE-%CI (STA) 

FREESPACE-%CA (STA) 

FREESPC~-BYTES (STA) 

HIGH-KEY (VLS) 

HISTORY CHIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT CHIS) 
RCVY-CI (HIS) 
RCVY-DEVT CHIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 

IMBED (CATT) 

INDEX (STA) 
ENTRIES/SECT (STA) 
HI-LEVEL-RBA (STA) 
LEVELS (STA) 
SEQ-SET=-RBA (STA) 

INH-UPDATE CATT) 

KEYLEN (CATT) 

LOW-KEY (VLS) 

MASTERPW (PRT) 

MAXLRECL (CATT) 

NOERASE (CATT) 

NOIMBED (ATT) 

NOREPLICAT (ATT) 

NOREUSE (ATT) 

EXCPS (STA) 

EXTENTS (STA) 

NOTUSABLE (ATT) 

NOWRITECHK (ATT) 

ORDERED (ATT3 

PHYRECS/TRK (VLS} 

PHYREC-SIZE (VLS) 

PROTECTION (PRT) 

RACF (PRT) 

HI-~ALLOC~RBA (ALC) 

HI-USED-RBA (ALC) 

HI-ALLOC-RBA (VLS) 

HI-USED-RBA (VLS) 

RECOVERY CATT) 

READPW (PRT) 

REC-DELETED (STA). 

REC~INSERTED (STA) 

REC-RETRIEVED (STA) 

REC~TOTAL (STA) 

REC-UPDATED (STA) 

REPLICATE (ATT) 

RKP (CATT) 

REUSE (ATT) 

SHROPTNS (ATT) 

SPACE-PRI (ALC) 

SPACE~SEC (ALC) 

SPACE-TYPE (ALC) 

SPEED (ATT) 

SPLITS-CA (STA) 

SPLITS-CI (STA) 

STATISTICS (STA) 

SUBALLOC (ATT) 

SYSTEM~TIMESTAMP (STA) 

TEMP-EXP (CATT) 

TRACKS/CA (VLS} 

UNORDERED (ATT) 

UNIQUE (ATT) 

UPDATEPW (PRT) 

USAR (PRT). 

USVR (PRT) 

VOLFLAG (VLS) 

VOLSER (VLS) 
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VOLUME (VLS) 
( ~ : WRITECHECK (ATT) 


Generation Data Group Base Entry Keywords 


ASSOCIATIONS (ASN) 
ATTRIBUTES (GDG) 
EMPTY (GDG) 
LIMIT (GDG) 
NOEMPTY (GDG) 
NOSCRATCH (GDG) 
SCRATCH (GDG) 
entryname (HIS) 
HISTORY (CHIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY=DEVT (HIS) 
RCVY~VOL CHIS) 
RELEASE (HIS) 
NONVSAM (ASN) 


Non-VSAM Entry Keywords 


ALIAS (ASN) 
ASSOCIATIONS (ASN) 
DEVTYPEC(VLS) 
entryname (HIS) 
FSEQN (NVS) 
HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION CHIS) 
fo OWNER-IDENT (HIS) 
( RCVY-CL (HIS) 
RCVY-DEVT (CHIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
VOLSER(VLS} 


Page Space Entry Keywords 


ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 
CODE (PRT) 
CONTROLPW (PRT) 
DATA (ASN) 
(HTS) 
HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (CHIS} 
OWNER-IDENT (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
INDEX (ASN) 
MASTERPW (PRT) 
PROTECTION (PRT) 
RACF (PRT) 
READPW (PRT) 
UPDATEPW (PRT) 
USAR (PRT) 
USVR (PRT) 
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Path Entry Keywords 


AIX (ASN) 
ASSOCIATIONS (ASN) 
ATTEMPTS (PRT) 
ATTRIBUTES CATT) 
CLUSTER (CASN) 
CODE (PRT) 
CONTROLPW (PRT) 
DATA (ASN) 
entryname (HIS) 
HISTORY (HIS) 
CREATION (HIS) 
EXPIRATION (HIS) 
JWNER-IDENT (HIS) 
RCOVY-CI (HIS) 
RCVY<-DEVT (HIS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
INDEX (ASN) 
MASTERPW (PRT) 
NOUPDATE (ATT) 
PROTECTION (PRT3 
RACF (PRT) 
READPW (PRT) 
UPDATE (CATT) 
UPDATEPW (PRT) 
USAR (PRT) 
USVR (PRT) 


User Catalog Entry Keywords 


ALIAS (ASN) 
ASSOCIATIONS (ASN) 
DEVTYPE(VLS ) 
entryname CHIS) 
HISTORY (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HIS} 
RCVY-VOL (CHIS) 
RELEASE (HIS) 
VOLFLAG (VLS) 
VOLSER (VLS) 


Volume Entry Keywords 


ATTRIBUTES (DSP) 
AUTOMATIC (DSP) 
EXPLICIT (DSP) 
MASTERCAT (DSP) 
SUBALLOC (DSP) 
UNIQUE (DSP) 

USERCAT (DSP) 
BYTES/TRK (VOL) 
CHARACTERISTICS (VOL) 
CYLS/VOL (VOL) 
DATASET-DIRECTORY (DSP) 

ATTRIBUTES (DSP) 

DSN (DSP) 

EXTENTS (DSP) 
DATASETS (DSP) 
DATASETS-ON-VOL (VOL) 
DATASPACE (DSP) 
DATASPCS-ON-VOL (VOL) 
DEVTYPE (VOL) 
EXTENT-DESCRIPTOR (DSP) 

BEG-CCHH (DSP) 

SPACE-MAP (DSP) 

TRACKS-TOTAL (DSP) 

TRACKS-USED (DSP) 
EXTENTS (DSP) 
FORMAT~1-DSCB (DSP) 
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CCHHR (DSP) 
_ TIMESTAMP (DSP) 
( MAX=PHYREC-SZ (VOL) 
MAX-EXT/ALLOC (VOL) 
HISTORY (HIS) 
RCVY-CI (HIS) 
RCVY-DEVT (HZS) 
RCVY-VOL (HIS) 
RELEASE (HIS) 
SEC ALLOC (DSP) 
TRKS/CYL (VOL) 
TYPE (DSP) 
CYLINDER (DSP) 
TRACK (DSP) 
(HIS) 


volume serial number 
VOLUME=TIMESTAMP (VOL) 


DESCRIPTION OF KEYWORD FIELDS 


This section contains a description of each field name. The 
field names are in the following groups of related information: 


Abbreviations Group Names 


ALC allocation group 

ASN associations group 

ATT attributes group 

DSP data space group 

GDG generation data group base entry, special fields 
, NVS non-VSAM entry, special field 
( HIS history group 

PRT protection group 

STA statistics group 

VLS volumes group 

VOL volume entry, special fields 


Groups are in alphabetic order. Field names within each group 
are in alphabetic order, not the order of appearance in the 
listed entry. 


ALC: ALLOCATION GROUP 


The fields in this group describe the space allocated to the 
data or index component defined by the entry. 


HI-ALLOC-RBA—The highest RBA Cplus 1) available within 
allocated space to store data. 


HI-USED-RBA—The highest RBA Cplus 1) within allocated space 
that actually contains data. 


SPACE-PRI-—-Gives the number of units Cindicated under TYPE) 
of space allocated to the data or index component when the 
cluster (that is, its data or index component) was defined. 
This amount of space is to be allocated whenever a data 
component Cor key range within it, and its associated 
sequence set, if IMBED is an attribute of the cluster) is 
extended onto a candidate volume. 


SPACE-SEC—Gives the number of units Cindicated under TYPE) 
of space to be allocated whenever a data set (or key range 
within it) is extended on the same volume. 
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SPACE-TYPE—-Indicates the unit of space allocation: 
CYLINDER—Cylinders 
TRACK——Tracks 


ASN: ASSOCIATIONS GROUP 
This group lists the type, such as cluster or data, and 
entrynames of the objects associated with the present entry. A 
cluster or alternate index entry will indicate its associated 
path entries and data and index Cif a key-sequenced data set) 
entries. Similarly, an index or data entry will indicate its 
associated cluster or the alternate index of which it is a 
component. 
@ An alias entry points to: 

- Its associated non-VSAM data set entry. 

_ A user catalog entry. (CA1] alias entries for a non-VSAM 
data set entry are chained together, as are alias 
entries for a user catalog entry.) 

e An alternate index entry points to: 

_ Its associated data and index entries. 

~ Its base cluster's cluster entry. 

~ Each associated path entry. 

@ An alternate index's data entry points to: 
~ Its associated alternate index entry. 

e An alternate index's index entry points to: 
~ Its associated alternate index entry. 

e A cluster entry points to: 
a Its associated data entry. 
_ Each associated path entry. 


— For a key~sequenced cluster, its associated index entry. 


~ For a cluster with alternate indexes, each associated 
alternate index entry. 


e A cluster's data entry points to: 
= Its associated cluster entry. 
e A cluster's index entry points to: 
= Its associated cluster entry. 
° A generation data group base entry points ta: 
os Its associated non-VSAM data set entries. 
e A non-VSAM data set entry points to: 


- Its associated alias entry. 


Its associated generation data group (for a G0000V00 
non-VSAM). 
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° A page space entry points to: 


= Its associated data entry. (The page space is cataloged 


as an entry~sequenced cluster with a cluster entry and 
an associated data entry. ) 


° A path entry Cthat establishes the connection between a base 


cluster and an alternate index) points to: 


= Its associated alternate index entry, and the alternate 
index's associated data and index entries. 


— The data entry of its associated base cluster. 


— For a key-sequenced base cluster, the index entry of its 


associated base cluster. 


e Path entry (that is an alias for a cluster entry) points to: 


~ Its associated base cluster entry. 
= The data entry of its associated base cluster. 


- For a key~sequenced cluster, the index entry of its 
associated base cluster. 


e A user catalog entry points to: 

= Its associated alias entry. 
AIX—-Identifies an alternate index entry. 
ALIAS~—-Identifies an alias entry. 
CLUSTER—-Identifies a cluster entry. 
DATA——Identifies a data entry. 
GDG-——Identifies a generation data group (GDG) base entry. 
INDEX——-Identifies an index entry. 
NONVSAM—Identifies a non-VSAM data set entry. 
PGSPC—-Identifies a page space entry. 
PATH——Identifies a path entry. 


UCAT—-Identifies a user catalog entry. 


ATTRIBUTES GROUP 


The fields in this group describe the miscellaneous attributes 
of the entry. See the DEFINE command for further discussion of 
most of these attributes. 


AVGLRECL—The average length of data records. AVGLRECL equals 
MAXLRECL when the records are fixed length. 


AXRKP——Indicates, for an alternate index, the offset, from the 
beginning of the base cluster's data record, at which the 
alternate~key field begins. 

BIND—The component is staged from mass storage to a direct 
access storage staging drive when it is opened, and it is 
retained (bound) in direct access storage until it is closed. 


BUFSPACE—The minimum buffer space in virtual storage to be 
provided by a processing program. 


CI/CA—The number of control intervals per control area. 


CISIZE—The size of a control interval. 
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CYLFAULT—The component is not staged from mass storage to a 
direct access storage staging drive when it is opened, but data 
from it is staged as the data is needed. 


DSTGWAIT—The component is destaged from direct access storage 
to mass storage before VSAM returns control to the program that 
is closing it. 


ERASE~——Records are to be erased (set to binary zeros) when 
deleted. | 


EXCPEXIT—The name of the object's exception exit routine. 


IMBED—The sequence-set index record is stored along with its 
associated data control area. 


INH-UPDATE—The data component cannot be updated. Either the 
data component was exported with INHIBITSOURCE specified, or its 
entry was modified by way of ALTER, with INHIBIT specified. 


INDEXED——The data component has an index; it is key sequenced. 
KEYLEN—The length of the key field ina data record. 


MAXLRECL—The maximum length of data or index records. AVGLRECL 
equals MAXLRECL when the records are fixed length. 


MAXRECS—Identifies the highest possible valid relative record 
number, for a relative record data set. This value is 
calculated as follows: 


2*“/CISIZE x number of records slots per control interval. 


NOERASE——-Records are not to be erased (set to binary 0's) when 
deleted. 


NOIMBED—-The sequence-set index record is not stored along with 
its associated data control area. 


NONINDEXED—The data component has no index; it is entry 
sequenced. 


NONSPANNED—Data records cannot span control intervals. 


NONUNIQKEY——Indicates, for an alternate index, that more than 
one data record in the base cluster can contain the same 
alternate-key value. 


NOREPLICAT—Index records are not replicated. 
NOREUSE—The data set cannot be reused. 


NOSWAP——The page space is a conventional page space and cannot 
be used as a high speed swap data set. 


NOTRKOVFL~—The physical blocks of a page space data set cannot 
span a track boundary... 


NOUPDATE——When the path is opened for processing, its associated 
base an is opened but the base cluster's upgrade set is not 
opened. 


NOUPGRADE-——The alternate index is not upgraded unless it is 
opened and being used to access the base cluster's data records. 


NOTUSABLE—The entry is not usable because (1) the catalog could 
not be correctly recovered by RESETCAT, or (2) a DELETE SPACE 
FORCE was issued for a volume(s) in the entry's volume list. 
NOWRITECHK—Write operations are not checked for correctness. 


NUMBERED—The cluster is a relative record data set. 
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ORDERED—Volumes are used for space allocation in the order they 
were specified when the cluster was defined. 


RECOVERY——-A temporary CLOSE is issued as each control area of 
the data set is loaded, so the whole data set won't have to be 
reloaded if a serious error occurs during loading. 


RECORDS/CI—Specifies the number of records, or slots, in each 
control interval of a relative record data set. 


RECVABLE—-This attribute is set in the data entry of a 
recoverable catalog, and each of the catalog's volumes contains 
a catalog recovery area. 


REPLICATE—-Index records are replicated (that is, each is 
duplicated around a track of the index's direct access device). 


REUSE—The data set can be reused (that is, its contents are 
one and its high-used RBA can be reset to 0 when it is 
opened). 


RKP—The relative key position-~the displacement from the 
beginning of a data record to its key field 


SHROPTNS—(Cn,m) The numbers n and m identify the types of 
sharing permitted. See SHAREOPTIONS in the DEFINE CLUSTER 
section for more details. 


SPANNED—Data records can be longer than control interval 
length, and can cross, or span, control interval boundaries. 


SPEED—-CLOSE is not issued until the data set has been loaded. 


SUBALLOC—More than one VSAM cluster can share the data space. 
A VSAM catalog might also occupy the data space. 


SWAP—The page space is a high speed swap data set used by 
Auxiliary Storage Management during a swap operation to store 
and retrieve the set of LSQA pages owned by an address space. 


TEMP-EXP——-The data component was temporarily exported. 


TRKOVFL—The physical blocks of a page space data set can span a 
track boundary. 


UNIQUE—Only one VSAM cluster or catalog can occupy the data 
space—the cluster or catalog is unique. 


UNIQUEKEY—Indicates, for an alternate index, that the 
alternate-key value identifies one, and only one, data record in 
the base cluster. 


UNORDERED-——Volumes specified when the cluster was defined can be 
used for space allocation in any order. 


UPDATE——-When the path is opened, the upgrade set's alternate 
indexes Cassociated with the path's base cluster) are also 
opened and are updated when the base cluster's contents change. 
UPGRADE—When the alternate index's base cluster is opened, the 
alternate index is also opened and will be updated to reflect 
any changes to the base cluster's contents. 


WRITECHECK—-Write operations are checked for correctness. 
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DSP: DATA SPACE GROUP 


The fields in this group are included by LISTCAT, as part of a 
volume entry, for each data space on the volume. If a volume 
contains no data spaces, it is a candidate volume. 





ATTRIBUTES——Describes the attributes of the data space. 


AUTOMATIC——The data space was created automatically by a 
secondary allocation operation. If a VSAM cluster must be 
given additional space on a volume and all existing data 
spaces are full, an existing data space will be extended, or 
a new one allocated on the volume, using catalog DADSM. A 
new data space so allocated is Known as an implicit or 
automatic data space. 


EXPLICIT—The data space was created explicitly by a DEFINE | 
MASTERCATALOG or USERCATALOG command, or a DEFINE | 
ALTERNATEINDEX or DEFINE CLUSTER command with the UNIQUE : 
attribute specified or by a DEFINE SPACE command. | 


MASTERCAT~—The data space contains the master catalog. 


SUBALLOC—The data space might contain several VSAM 
clusters. 


USERCAT—The data space contains a user catalog. 


UNIQUE—The data space contains a single Cunique) VSAM 
cluster or catalog. 


DATASET DIRECTORY—Lists the VSAM data sets that can be stored 
(see CANDIDATE below) or actually are stored (in whole or in 
part) in the data space. 


ATTRIBUTES——Describes the relation between the named data 
set and the data space. 


CANDIDATE—The volume is a candidate for storing the 
data set 


(NULL)——The data set is stored Cin whole or in part) in 
the data space 


DSN——The data set name of the object that can be stored or 
is stored on the volume. 


EXTENTS-—The number of data set extents for the data set 
within the data space. 


DATASETS——The number of VSAM data sets stored Cin whole or in 
part) in the data space. (The number includes data sets for 
which the volume is a candidate. ) 


EXTENT-DESCRIPTOR—Describes the data space extent. 


BEG-CCHH—The device address (that is, CC = cylinder and HH 
= track) of the extent. 


SPACE-MAP——-A hexadecimal number that tells what tracks are 
used and what tracks are free in the extent. The number 
consists of one or more run length codes C(CRLCs). The first 
RLC gives the number of contiguous used tracks, starting at 
the beginning of the extent; if all the tracks in the extent 
are used, there is only one RLC. The second RLC gives the 
number of contiguous free tracks, beyond the used tracks. A 
third RLC gives used tracks again, a fourth gives free 
tracks, and so on. 


A l-byte RLC gives the number of tracks less than or equal 
to 250; a 3-byte RLC gives the number of tracks greater than © | 
250. That is, if the first byte of an RLC is X'FA' (250) or {7 
less, it is the only byte of the RLC and gives the number of 
tracks. If the first byte of an RLC is X'FB* €251) or more, 


on 
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the byte is followed by two more bytes that give the number 
of tracks (the first byte indicates merely to look at the 
next two bytes). 


TRACKS-TOTAL—Allocated to the data space altogether. 
TRACKS-USED—Used to store data. 
EXTENTS—-The number of data space extents in the data space. 


FORMAT-1-DSCB—Identifies the format-1 DSCB that describes the 
data space. 


CCHHR—The device address (that is, CC = cylinder, HH = 
track, and R = record number) of the DSCB in the VTOC. 


TIMESTAMP——The time the data space was allocated (system 
time-of-day clock value). The DSCB contains the timestamp 
as part of the VSAM~generated name. 


SEC-ALLOC-——Gives the number of units Cindicated under TYPE) of 
space to be allocated whenever the data space is extended. 


TYPE—Indicates the unit of space allocation: 
CYLINDERS—Cylinders 
TRACK-~-~—Tracks 


GDG: GENERATION DATA GROUP BASE ENTRY, SPECIAL FIELDS 


The special fields for a generation data group base entry 
describe attributes of the generation data group. 


ATTRIBUTES 
This field includes the following fields: 


EMPTY 
All generation data sets in the generation data group 
will be uncataloged when the maximum number Cgiven 
under LIMIT) is reached and one more data set is to be 
added to the group. 


LIMIT 
The maximum number of generation data sets allowed in 
the generation data group. 


NOEMPTY | 
Only the oldest generation data set in the generation 
data group will be uncataloged when the maximum number 
Cgiven under LIMIT) is reached and one more data set 
is to be added to the group. 


NOSCRATCH | 
Generation data sets are not to be scratched (see 
SCRATCH below) when uncataloged. 


SCRATCH 
Generation data sets are to be scratched (that is, the 
DSCB that describes each one is removed from the VTOC 
of the volume on which it resides) when uncataloged. 
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NVS: NON-VSAM ENTRY, SPECIAL FIELD 


The special field for a non-VSAM data set describes a non-VSAM 
data set stored on magnetic tape. . 


FSEQN-——The sequence number (for the tape volume indicated under 
the "VOLUMES group" keyword VOLSER) of the file in which the 
non-VSAM data set is stored. 


HIS: HISTORY GROUP 


The fields in this group identify the object's owner, identify 
its catalog recovery volume and release level, and give the 
object's creation and expiration dates. 


entryname—The name of the cataloged object. The entryname can 
be specified with the ENTRIES Paneener of LISTCAT to identify a 
catalog entry. 


HISTORY——This field includes the following fields: 


CREATION—The Julian date Cyy.ddd) on which the entry was 
created. This field will always contain 00.000 for a 
non-VSAM data set entry in an OS CVOL 


EXPIRATION—-The Julian date Cyy.ddd) after which the entry 
can be deleted without specifying the PURGE parameter in the 
DELETE command. Julian date 99.999 indicates that PURGE is 
always required to delete the object. This field will 

a el contain 00.000 for a non-VSAM data set entry in an OS 


OWNER-IDENT——The identity of the owner of the object 
described by the entry. 


RCVY-CI—If the entry is ina recoverable catalog, this 
field contains the control interval number in the catalog 
recovery area where a duplicate of the entry can be found. 


RCVY-DEVT-—If the entry is in a recoverable catalog, this 
field identifies the recovery volume's device type. (See 
the Device Type Translate Table at the end of this section 
for a translation of the hexadecimal device type to its 
equivalent EBCDIC value.) 


RCVY-VOL-——If the entry is ina ee catalog, this 
field contains the recovery volume's serial number. 


RELEASE—The release of VSAM under which the entry was 


created: 
1 = OS/VS2 Release 3 and releases preceding Release 3 
2 = OS/VS2 Release 3.6 and any later releases 


PRT: PROTECTION GROUP 


The fields in this group describe how the alternate index, 
cluster, data component, index component, or path defined by the 
entry is password protected or RACF protected. NULL or 
SUPPRESSED might be listed under password protection and YES or 
NO might be listed under RACF protection. 


NULL indicates that the object defined by the entry has no 
passwords. | 


SUPP indicates that the master password of neither the catalog 
nor the entry was specified, so authority to list protection 
information is not granted. | 

RACF—Indicates whether or not the entry is protected by the 
Resource Access Control Facility. 


270 MVS/XA VSAM Catalog: Access Method Services Reference 























YES~——Entry is RACF protected. | 
NO——-Entry is not RACF protected. 


ATTEMPTS——Gives the number of times the console operator is 
allowed to attempt to enter a correct password. 


CODE—Gives the code used to tell the console operator what 
alternate index, catalog, cluster, path, data component, or 
index component requires him to enter a password. NULL is 
listed under CODE if a code is not used-—the object requiring 
the password is identified with its full name. 


CONTROLPW—The control interval password (that is, the password 
for control interval access). NULL indicates no control 
interval password. 


MASTERPW——The master password. 


READPW—The read-only password. NULL indicates no read-only 
password. 


UPDATEPW—The update password. NULL indicates no update 
password. 


USAR—The contents (1 to 255 bytes, in character format) of the 
USAR Cuser-security-~authorization record). This is the 
information specified in the string subparameter of the AUTH 
Ssubparameter of the DEFINE command. 


USVR—The name of the USVR Cuser-security-verification routine) 
pica ie to be invoked to verify authorization of any access to 
e entry. 


STA: STATISTICS GROUP 





The fields in this group give numbers and percentages that 
indicate how much activity has taken place in the processing of 
a data or index component. The statistics in the catalog are 
updated when the data set is closed. Therefore, if a failure 
occurs during CLOSE, the statistics may not be valid. Because a 
VSAM catalog remains open from job to job, its statistics are 
not updated. 


Statistic values can be any value from a minus to a large 
number, if a failure occurs before or during close processing. 
VERIFY will not correct these statistics. 


FREESPACE-%CI—Percentage of space to be left eee in a control 
interval for subsequent processing. 


FREESPACE~%CA—Percentage of control intervals to be left free 
in a control area for subsequent processing. 


FREESPC-BYTES——Actual number of bytes of free space in the total 
amount of space allocated to the data or index component. “ree 
space in partially used control intervals is not included i 

this statistic. 


INDEX—This field appears only in an index entry. The fie.ids 
under it describe activity in the index component. 


ENTRIES/SECT—The number of entries in each section of 
entries in an index record. 


HI-LEVEL-RBA—The relative byte address (RBA) of the 
highest-level index record. 


LEVELS—The number of levels of records in the index. The 
number is 0 if no records have been loaded into the 
key~sequenced data set to which the index belongs. 
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VLS: VOLUMES GROUP 





SEQ-SET=-RBA-——The RBA, in decimal, of the first sequence-set 
record. The sequence set might be separated from the index a 
set by some quantity of RBA space. 3 
. ed 
The remaining fields in the statistics group (Cexcept for the 

ot tae timestamp field), are updated only when the data set is 

closed. 


EXCPS-——EXCP Cexecute channel program-—SVC 0) macro instructions 
issued by VSAM against the data or index component. 


EXTENTS-——-Extents in the data or index component. 


REC-DELETED—-The number of records that have been deleted from 
the data or index component. Statistics for records deleted are 
not maintained when the data set is processed in control 
interval mode. 


REC-INSERTED—For a key-~sequenced data set, the number of 
records that have been inserted into the data component before 
the last record; records originally loaded and records added to 
the end are not included in this statistic. For relative record 
data sets, it is the number of records inserted into available 
slots; the number of records originally loaded are included in 
this statistic. Statistics for records inserted are not 

sins aa age when the data set is processed in control interval 
mode. 


REC-RETRIEVED—-The number of records that have been retrieved 
from the data or index component, whether for update or not for 
update. Statistics for records retrieved are not maintained 
when the data set is processed in control interval mode. 


REC-TOTAL—The total number of records actually in the data or 
index component. This statistic is not maintained when the data 
set 1s processed in control interval mode. 


REC-UPDATED——The number of records that have been retrieved for 
update and rewritten. This value does not reflect those records 
that were deleted, but a record that is updated and then deleted 
is counted in the update statistics. Statistics for records 
updated are not maintained when the data set is processed in 
control interval mode. 


SPLITS-CA—Control area splits. Half the data records in a 
control area were written into a new control area and then were 
deleted from the old control area. 


SPLITS-CI—Control interval splits. Half the data records in a 
control interval were written into a new control interval and 
then were deleted from the old control interval. 


SYSTEM-TIMESTAMP——The time (system time-of~day clock value) the 
data or index component was last closed (after being opened for 
operations that might have changed its contents). 


The fields in this group identify the volume(s) on which a data 
component, index component, user catalog, or non-VSAM data set 
is stored. It also identifies candidate volume(s) for a data or 
index component. The fields describe the type of volume and 
give, for a data or index component, information about the space 
the object uses on the volume. | 


e If an entry~sequenced or relative record cluster'’s data 
component has more than one VOLUMES group, each group 
describes the extents that contain data records for the 
cluster on a specific volume. gs 


« If a key-sequenced cluster's data component has more than Ly 
one VOLUMES group, each group describes the extents that ! 
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contain data records for the cluster, or one of its key 
ranges, ona specific volume. 


e If a key~sequenced cluster's index component has more than 
one VOLUMES group, each group describes the extents that 
contain index records for the cluster, or one of its Key 
ranges, on a specific volume. The first VOLUMES group 
describes the extent that contains the high-level index 
records (that is, index records in levels above the sequence 
set level). Each of the next groups describe the extents 
that contain sequence-set index records for the cluster, or 
one of its key ranges, on a specific volume. The index 
component of a key~sequenced data set with the IMBED 
attribute will have a minimum of two volume groups, one for 
the imbedded sequence set, and one for the high-level index. 
The extents for the imbedded sequence set will be the same 
as those for the data component. 


BYTES/TRACK-——The number of bytes that VSAM can write ona track 
Clisted for page spaces only). 


DEVTYPE—The type of device to which the volume belongs. (See 
the Device Type Translate Table at the end of this section for a 
translation of the hexadecimal device type to its equivalent 
EBCDIC value.) 


EXTENT-NUMBER——The number of extents allocated for the data or 
index component on the volume. 


EXTENT-TYPE—The type of extents: 


00—The extents are contiguous 

40—The extents are not preformatted 

80—A sequence set occupies a track adjacent to a control 
area. 


Se a ee the physical and relative byte addresses of each 
extent. 


HIGH-CCHH—The device address (that is, CC = cylinder and HH 
= track) of the end of the extent 

HIGH-RBA—The RBA Crelative byte address), in decimal, of 
the end of the extent. 

LOW-CCHH-~—-The device address (that is, CC = cylinder and HH 
= track) of the beginning of the extent. 

LOW=RBA——The RBA Crelative byte address), in decimal, of the 
beginning of the extent. | 
TRACKS——-The number of tracks in the extent, from low to high 
device addresses. 


HIGH-KEY*——For a key-sequenced data set with the KEYRANGE 
attribute, the highest hexadecimal value allowed on the volume 
in the key field of a record in the ney range. A maximum of 64 
bytes can appear in HIGH-KEY. 


HI-KEY-RBA*——For a key-~sequenced data set, the RBA Crelative 
byte address), in decimal, of the control interval on the volume 
that contains the highest keyed record in the data set or Key 
range. 


LOW-KEY*—For a key~sequenced data set with the KEYRANGE 
attribute, the lowest hexadecimal value allowed on the volume in 
the Key field of a record in the Key range. A maximum of 64 
bytes can appear in LOW-KEY. 


2 Multiple key ranges may reside on a single volume; the 
volumes group is repeated for each such Key range field. 
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PHYRECS/TRK—The number of physical records (of the size 
indicated under PHYRECS-SIZE) that VSAM can write on a track on = 
the volume. © f 


PHYREC-SIZE—The number of bytes that VSAM uses for a physical 
record in the data or index component. 


HI-ALLOC-RBA—The highest RBA Cplus 1) available within 
allocated space to store data component, its key range, the 
index component, or the sequence set records of a key range. 


HI-USED-RBA—The highest RBA Cplus 1) within allocated space 
that actually contains data component, its key range, the index 
component, or the sequence set records of a key range. 


TRACKS/CA—The number of tracks in a control area in the data 
component. (This value is computed when the entry is defined, 
and reflects the optimum size of the control area for the given 
device type and the nature of the entry-—whether indexed, 
nonindexed, or numbered.) For a key~sequenced data set with the 
imbedded attribute, this value includes the sequence set track. 


VOLFLAG—Indicates whether the volume is a candidate volume, the 
alld ap a subsequent volume on which data in a given key range 
is stored. 


CANDIDATE—The volume is a candidate for storing the data or 
index component. 





OVERFLOW—The volume is an overflow volume on which data 
records ina key range are stored. The KEYRANGE begins on 
another CPRIME) volume. 


PRIME—The volume is the first volume on which data records 
in a key range are stored. 


VOLSER—The serial number of the volume. 


VOL: VOLUME ENTRY, SPECIAL FIELDS FOR 


The special fields for a volume entry describe the 
characteristics of the space that VSAM uses on the volume. 


volume serial number—The name of the cataloged volume entry. 
The volume serial number can be specified with the ENTRIES 
parameter of LISTCAT to identify the volume entry. 


BYTES/TRK——-The number of bytes that VSAM can use on each track 
on the volume. 


CYLS/VOL——The number of cylinders that VSAM can use on the 
volume, including alternate track cylinders. 


DATASETS-ON-VOL—The number of VSAM clusters that reside, in 
oe or in part, on the volume. This includes candidate 
volumes. 


DATASPCS-ON-VOL-——The number of VSAM data spaces on the volume. 
Should the number of data spaces be zero, then this is a 
candidate volume only, and the data space group is omitted. 


DEVTYPE—The type of device to which the volume belongs. (See 
the Device Type Translate Table at the end of this section for a 


translation of the hexadecimal device type to its equivalent 
EBCDIC value.) 


MAX-PHYREC-SZ—The size of the largest physical record that VSAM 
can write on the volume. 


MAX-EXT/ALLOC——-The maximum number of extents that can be (ff 


allocated per each allocation request for a single data set on GQ 
the volume. se 
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TRKS/CYL—-The number of tracks in each cylinder on the volume. 


VOLUME-TIMESTAMP—The time (system time-of-day clock value) VSAM 
last changed the contents of the volume. The format-4 DSCB 
contains the timestamp at offset 76 (X'"4C*'). 





DEVICE TYPE TRANSLATE TABLE 


LISTCAT Code Device Type 

3000 8001 9 TRK TAPE 

3010 200C 3375 

3010 200E 33804 

3040 200A 3340 €35M/’70M) 

3050 2006 2305-1 

3050 2007 2305-2 

3050 2009 3330 

3050 200B 53350 

3050 200D 3330-1 

3058 2009 3330V 

3080 8001 7 TRK TAPE 

30C0 2008 2314/2319 

3200 8003 9 TRK, 6250 BPI TAPE 
3400 8003 9 TRK, 1600 BPI TAPE 


Refer to ah Area poser tp eaen of ane Unit Control ae CUCB)"™ 





in | 
additional a AfoOrnetion on device types. 





: 53580 models A04, AAG, BOG, ADG, BDG, AES, and BEG. 
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EXAMPLES OF LISTCAT OUTPUT LISTINGS 


This section illustrates the kind of output you can get when you 
specify LISTCAT parameters. It also describes the job control 
language you can specify and the output messages you receive 
when the LISTCAT procedure executes successfully. 


JOB CONTROL LANGUAGE (JCL) FOR LISTCAT JOBS 


The job control language (JCL) statements that can be used to 
list a catalog's entries are: 


//LISTCAT JOB 
//STEP1 EXEC PGM= IDCAMS 
//STEPCAT DD DSN=YOURCAT, DISP=SHR 
//QUTDD DD DSN=LISTCAT . OUTPUT, UNIT=TAPE, 
// VOL=SER=TAPE1LO,LABEL=C€1,NL),DISP=CNEW, KEEP), 
// DCB=CRECFM=VBA, LRECL=125, BLKSIZE=629) 
//SYSPRINT DD SYSOUT=A 
S/SYSIN DD X 
LISTCAT - 
CATALOGCYOURCAT/PASSWORD) - 
OUTFILECOUTDD) - 


7% 


The JOB statement contains user and accounting information 
required for your installation. 


The EXEC statement identifies the program to be executed, IDCAMS 
(that is, the access method services program). 


® STEPCAT DD, which allocates your catalog. The catalog can 
be allocated dynamically if the STEPCAT and JOBCAT are 
omitted. If the catalog is dynamically allocated, its 
volume must be mounted as permanently RESIDENT or RESERVED. 


e OUTDD, which specifies an alternate output file, so that the 
LISTCAT output can be written onto an auxiliary storage 
device. The LISTCAT command's OUTFILE parameter points to 
the OUTDD DD statement. Only the LISTCAT output is written 
to the alternate output device. JCL statements, system 
messages, and job statistics are written to the SYSPRINT 
output device. 


~ DSN=LISTCAT.OUTPUT specifies the name for the magnetic 
tape file. 


_- UNIT=2400-3 and VOL=SER=TAPE10O specifies that the file 
is to be contained on magnetic tape volume TAPE1O. 


- LABEL=C1,NL) specifies that this is the first file on a 
nonlabeled tape. You can also use a standard labeled 
tape by specifying LABEL=(1,SL). If subsequent job 
steps produce additional files of LISTCAT output on the 
same tape volume, you should increase the file number in 
each job step's LABEL subparameter (that is, 

LABEL=(€2,NL) for the second job step, LABEL=C€3,NL) for 
the third job step, and so on.) 


- DISP=C(CNEW,KEEP) specifies that this is a new wre file 
and is to be rewound when the job finishes. 
subsequent job step prints the tape, DISP= (NEW. PASS) 
should be specified. If your job step contains more 
than one LISTCAT command, DISP=(MOD,KEEP) or 
DISP=C(MOD,PASS) can be used to concatenate all of the 
LISTCAT output in one sequential file. 


_- DCB=CRECFM=VBA, LRECL=125, BLKSIZE=629) specifies that the 
LISTCAT output records are variable-length, blocked 
5-to-l1, and are preceded by an ANSI print control 
character. 
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® SYSPRINT DD, which is required for each access method 
services job step. It identifies the output queue, 
SYSOUT=A, on which all LISTCAT output and system output 
messages are printed Cunless the OUTFILE parameter and its 
associated DD statement is specified-—see OUTDD above). 


Note: If you want all output to be written to an auxiliary 
storage device, replace "OUTDD' with ‘'SYSPRINT! in the OUTDD DD 
statement and omit the SYSPRINT DD SYSOUT=A statement. 


® SYSIN DD, which specifies, with an asterisk (%), that the 
statements that follow are the input data statements. 
"/*X" terminates the input data statements. 


The LISTCAT command parameters shown above are common to the 
LISTCAT examples that follow. Other LISTCAT parameters are 
coded with each example and the output that results is 
illustrated. These two parameters are optional: 


® CATALOG, which identifies the catalog, YOURCAT, whose 
entries are to be listed. If the catalog is password 
protected, its read- or higher-level password, PASSWORD, is 
required. If the passwords and protection attributes of 
each entry are to be listed, the catalog's master password 
is required. 


° OUTFILE, which points to the OUTDD DD statement. The OUTDD 
DD statement allocates an alternate output file for the 
LISTCAT output. 


If you want to print the LISTCAT output that is contained on an 
alternate output file, you can use the IEBGENER program. The 
following shows the JCL required to print the alternate output 
file, LISTCAT.OUTPUT, that was allocated previously: 


//PRINTOUT JOB 


S/STEPI EXEC PGM=IEBGENER 

S/SYSUT1 DD DSN=LISTCAT .OUTPUT,UNIT=2400-5, 

// VOL=SER=TAPE10,LABEL=(1,NL),DISP=COLD,KEEP), 
// DCB=C(RECFM=VBA,LRECL=125, BLKSIZE=629) 


f/SYSUT2 DD SYSOUT=A 
77SYSPRINT DD SYSOUT=A 
S/SYSIN DD DUMMY 
7% 
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LISTCAT AND ACCESS METHOD SERVICES OUTPUT MESSAGES 


When the LISTCAT job completes, access method services provides 
messages and diagnostic information. An analysis of any error 
messages received can be found in Message Library: System 

- When your LISTCAT job completes successfully, access 
method services provides messages that follow the entry listing 
(see Figure 10): 





LISTING FROM CATALOG -- MJKCAT 
THE Renee ENTRIES PROCESSED WAS: 


ALIAS ----------------- 2 
CLUSTER --------------- 5 
DATA ------------------ 6 
GDG ------------------- 1 
INDEX ----------------- 3 
NONVSAM --------------- 2 
PAGESPACE -~----------- 0 
PATH ------------------ 2 

E ----------------- 0 
USERCATALOG ----------- 0 
TOTAL -------~-------- 22 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 
IDCOOO1I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 
IDCOQ0O02I IDCAMS PROCESSING COMPLETE, MAXIMUM CONDITION CODE WAS 0 


Figure 10. Messages That Follow the Entry Listing 


The first line identifies the catalog that contains the listed 
entries. 


The next group of lines specify the number of each entry type 
and the total number of entries that were listed. This 
statistical information can help you determine the approximate 
size, in records, of your catalog. 


The next line specifies the number of entries that could not he 
listed because the appropriate password was not specified. 


The last two messages indicate that the LISTCAT command 
CFUNCTION) and the job step CIDCAMS) completed successfully. 
delle yr aie is invoked from a TSO terminal, IDCOOO1I is not 
printed. 
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LISTCAT OUTPUT LISTING 


When you specify LISTCAT with no parameters, the entryname and 
type of each entry are listed (see Figure 11 on page 280). The 
same listing would result if the NAMES parameter were specified. 


You can use this type of listing to list the name of each 
cataloged object and to determine the number of entries in the 
catalog. The total number of entries is an approximate size, in 
records, of your catalog. 
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/% LIST ENTRYNAMES OF THE CATALOG X/ 
LISTCAT - | , 
CATALOG (MJKCAT) 


LISTING FROM CATALOG -- MJKCAT 


Aix SSesseseer= MJK.ALT.INDEX1 
DATA: e==-=== MJK.ALT.INDEX1.DATA 
INDEX. er<<=- MJK.ALT.INDEX1 . INDEX 
PATH @te="2= MJK.AIX1.PATH 
CLUSTER: ==+<<== MJK.CLUSTERI 
DATA ~------ MJK.CLUSTER. DATA 
INDEX <<---=-= MJK.CLUSTERI . INDEX 
GDG BASE -----~ MJK.GDG1 
NONVSAM ---- MJK.GDG1.G0001V00 
ALIAS: S23 r eee = MJK.GDG1.ALIAS 
NONVSAM ------- MJK.NONVSAM1 
CLUSTER, ==<4"2= MJKCAT 
DATA co es<s= “VSAM. CATALOG. BASE. DATA. RECORD 
INDEX = =<3== VSAM.CATALOG. BASE. INDEX.RECORD 
VOLUME =======+= 3335001 


LISTING FROM CATALOG -- MJKCAT 


THE ie ENTRIES PROCESSED WAS: 


ALIAS ----------------- 1 
CLUSTER --------------- 2 
DATA ~----~------------ 3 
GDG ------------------- 1 
INDEX ---~------------- 3 
NONVSAM ---~~---------- 2 
PAGESPACE ------------- 0 
PATH ------------------ 1 
SPACE ----------------- 0 
USERCATALOG ----------- 0 
TOTAL ---------------- 14 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 








IDCOOO1I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 
IDCO002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 


Figure ll. 


Example of LISTCAT Output When No Parameters Are Specified 
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LISTCAT VOLUME OUTPUT LISTING 


When the LISTCAT command is specified with the VOLUME parameter, 

the volume serial number and device type of each volume that 
ee oe or all of the cataloged object are listed (see 
igure : 


7* LIST VOLUMES FOR EACH ENTRY #/ 


LISTCAT - 
VOLUME - 
CATALOG (MJKCAT) 


LISTING FROM CATALOG -- MJKCAT 


AIX sone erenn-- MJK ALT. INDEX! 
HISTORY 
OWNER-IDENT------- (NULL) 
RELEASE---------------- 2 
DATA ------- MJK ALT. INDEXL.OATA 
HISTORY 
OWNER-IDENT------- (NULL) 
RELEASE ---------------- 2 
VOLUMES 
VOLSER-----e---<--- 333001 
INDEX ------ MJK ALT. INOEX1 . INDEX 
HISTORY 
OWNER-IDENT-~------ (NULL) 
RELEASE----------~--~--- 2 
VOLUNES 
VOLSERen ree nneene~ 333001 
PATH ------- MJK .AIX1.PATH 
HISTORY 
OWNER-IDENT--~----- (NULL) 
RE LEASE ---------------- 2 
CLUSTER ------- MJK .CLUSTER1 
HISTORY 
OWNER-IDENT----- OWNCLUST 
RE LEASE ---------------- 2 
DATA ------- MJK.CLUSTER.DATA 
HISTORY 
OKNER-IDENT------- (HULL) 
RELEASE nnn een e ee cen=-- 2 
VOLUMES 
VOLSER------------ 333001 
INDEX «----- MJK ..CLUSTER1 . INDEX 
HISTORY 
OWHER-IDENT------- (NULL) 
RELEASE owen nnn nnn eee === 2 
VOLUMES 
VOLSER~------------ 333001 
GOG BASE ------ MJK.GDG1 
HISTORY 
OWNER-IOENT------- OWNGOG 
RELEASE~-~-- een en --- === 2 
NONVSAM ---- MJK.G0G1.G0001V00 
HISTORY 
OWNER-IDENT------- (NULL) 
RELEASE ---22----------- 2 
VOLUMES 
VOLSER~-~--------- 333001 
VOLSER------------ 333002 
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CREATION---------- 77.040 
EXPIRATION-------- 00.000 
CREATION---------- 77.040 
EXPIRATION-------- 00.000 
DEVTYPE------ X'30502009" 
CREATION---------- 77.040 
EXPIRATION-------- 00.000 
DEVTYPE------ X' 30502009" 
CREATION---------- 77.040 
EXPIRATION-------- 00.000 
CREATION~--------- 77.040 
EXPIRATION-------- 77.140 
CREATION---------- 77.040 
EXPIRATION---~----- 00.000 
DEVTYPE------ X*30502009° 
CREATION---------- 77.040 
EXPIRATION-------- 00.000 
DEVTYPE------ X'30502009° 
CREATION---------- 77.040 
EXPIRATION-------- 99.365 
CREATION-~-~-~------ 77.040 
EXPIRATION-------- 00.000 
DEVTYPE------ X'30502009° 
DEVTYPE------ X'30502009' 








RCVY-VOL---------- 333001 
RCVY-DEVT----X' 30502009’ 


RCVY-VOL~---------- 333001 
RCVY -DEVT-~--X* 30502009’ 


RCVY -V0Lonn nen n en 333001 
RCVY-DEVT----X'30502009' 


RCVY-VOL---~------- 333091 
RCVY-DEVT--~--X' 30502009' 


RCVY-VOL~---------- 333001 
RCVY-DEVT~--~-X' 30502009' 


RCVY-VOL---------- 333001 
RCVY-DEVT----X*30502009' 


RCVY-VOL---------- 333001 
RCVY-DEVT~---X' 30502009" 


RCVY-VOL---------- 333001 
RCVY-DEVT--~--X‘*30502009' 


RCVY-VOL---------- 333001 
RCVY-DEVT----X’ 30502009’ 


Example of LISTCAT VOLUME Output 





RCVY-CI-------- X'000010' 
RCVY-CI-------- X'Q00011' 
RCVY-CI-------- X'000012' 
RCVY-CI-------- X'000014' 
RCVY-CI-------- X'OOO0CE 
RCVY-CI-------- X'00000D‘ 
RCVY-CI-------- X'OOO00F® 
RCVY-CI-------- X'000015' 
RCVY-CI-------- X'000016' 
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NONVSAM ---- MJK.NONVSAM1 


HISTORY : 
OKNER-IDENT------- (NULL) CREATION---------- 77.040 
RELEASE ---------------- 2 EXPIRATION-------- 00.000 

VOLUMES 
VOLSER------------ 333001 DEVTYPE------ X*30502009' 

CLUSTER ------- MJKCAT 

HISTORY 
OWHER-IDENT------- (NULL) CREATION---------- 77.040 
RELEASE ---------------- 2 EXPIRATION--~----- 99.999 

DATA ------- VSAM.CATALOG.BASE .DATA.RECORD 

HISTORY 
OKNER - IDENT------- (NULL) CREATION---------- 00.000 
RE LEASE---------------- 2 EXPIRATION-------- 00.000 

VOLUNES 
VOLSER--~---------- 333001 DEVTYPE------ X'30502009° 

INDEX ------ VSAM.CATALOG.BASE . INDEX.RECORD 

HISTORY 
OWHNER-IDENT------- (NULL) CREATION---------- 00.000 
RELEASE ---------------- 2 EXPIRATION-------- 00.000 

VOLUNES 
VOLSER~------------ 333001 DEVTYPE------ X* 30502009" 

VOLUME -------- 333001 

HISTORY 
RELEASE ---------------- 2 RCVY-VOL---------- 333001 

VOLUMES 
VOLSER------------ 333001 DEVTYPE------ X'30502009' 


LISTING FROM CATALOG -- MJKCAT 


THE NUMBER OF ENTRIES PROCESSED WAS: 


AIX ------------ eaenee= ! 
ALIAS ----------------- 0 
CLUSTER --------------- 2 
DATA ---+---~--~-~------- 3 
G0G ------------------- 1 
INDEX ----------------- 3 
NONVSAM --------------- 2 
PAGESPACE ------------- 0 
PATH ------------------ 1 
SPACE ----------------- 1 
USERCATALOG ~----------- 0 
TOTAL --~------------- 14 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 


IOCOOOII FUNCTION COMPLETED, HIGHEST CONOITION CODE WAS 0 


TOCO002T IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 


Figure 12 (Part 2 of 2). 





RCVY=VOL=+=+---<<- 333001 
RCVY-DEVT--~--X'30502009' 


RCVY-DEVT----X' 30502009’ 


Example of LISTCAT VOLUME Output 
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RCVY-CI 


RCVY-CI 


X*000009' 


| as 5 ae 








—~ 





LISTCAT SPACE ALL OUTPUT LISTING 


When the LISTCAT command is specified with the SPACE and ALL 
parameters, all the information for each volume entry in the 
catalog is listed (see Figure 13). You can use this type of 
listing to determine how space on each cataloged volume is 
allocated to VSAM data spaces. You may have to list the 
volume's table of contents CVTOC) to determine how all of the 
volume's space is allocated. 





7% LIST VOLUME INFORMATION FOR THE VOLUMES. - 
CONTROLLED BY THE CATALOG */ 


LISTCAT - 
SPACE - 
ALL - 
CATALOG( MJKCAT ) 
LISTING FROM CATALOG -- MJKCAT 
VOLUME -------- 333001 
HISTORY 
RELEASE -2<- nn nnn === 2 RCVY-VOL---------- 333001 RCVY-DEVT~---~X' 30502009 RCVY-CI-<------- X'000009° 
CHARACTERISTICS 
BYTES/TRK---------- 13165 DEVTYPE------ X*30502009' MAX-PHYREC-SZ~-~---- 13030 DATASETS-ON-VOL-------- 5 
TRKS/CY Lon----- eee 19 VOLUME -TIMESTAMP: MAX-EXT/ALLOC---~=------ 5 DATASPCS-ON-VOL------~-- 1 
CYLS/VOL------------- 411 X*8A51B6A76850E000° 
DATASPACE 
DATASETS--------------- 5 FORMAT-1-DSCB: ATTRIBUTES: 
EXTENTS---9 een eee eo --- 1 CCHHR------ X*0000000103' SUBALLOC 
SEC-ALLOC-----~------- 40 TIMESTAMP EXPLICIT 
TYPE ween enn nee ne--- TRACK X'8A51B61D97B04000 USERCAT 
EXTENT-DESCRIPTOR: 
TRACKS-TOTAL--------- 160 BEG-CCHH----- X*00000002' SPACE -MAP---~------- 5947 
TRACKS-USED----------- 89 
DATASET-DIRECTORY: 
OSN----MJKCAT ATTRIBUTES-------- (NULL) EXTENTS -----eeer er nn--- 3 
DSN----MJK .CLUSTER.DATA ATTRIBUTES-------- (NULL) EXTENTS-----eeroero---- 1 
OSN----MJK .CLUSTERI . INDEX ATTRIBUTES--~----- (NULL) EXTENTS~~--3----------- 1 
DSN----MJK .ALT.IHDEX1.OATA ATTRIBUTES--~----=-( HULL) EXTENTS ----2----------- I 
DSN----MJK .ALT. INDEX! . INDEX ATTRIBUTES~--~------ (NULL) EXTENTS<-~-- <3 2 --e------ 1 


LISTING FROM CATALOG -- MJKCAT 


THE NUMBER OF ENTRIES PROCESSED WAS: 


AIX ------------------- 0 
ALIAS ----------------- 0 
CLUSTER --------------- 0 
DATA ------------------ 0 
60G ------------------- 0 
INDEX ----------------- 0 
NONVSAM --------------- 0 
PAGESPACE ------------- 0 
PATH ------------------ 0 
SPACE ----------------- 1 
USERCATALOG ----------- 0 
TOTAL ----------------- 1 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 
IOCOOO1I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 


IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 
Figure 13. Example of LISTCAT SPACE ALL Output 
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LISTCAT ALL OUTPUT LISTING 


When you specify the LISTCAT command and include the ALL 
parameter, all the information for each catalog entry is listed. 
The example in Figure 14 on page 285 illustrates the LISTCAT 
output for each type of catalog entry. You can use this type of 
listing to obtain all cataloged information (except password and 
security information) about each entry that is listed. When you 
want to list an entry's passwords, you must provide the 
catalog's master password (which results in listing the 
passwords of each password~protected entry) or each entry's | 
master password. 





Note: When ENTRIES is specified, you specify only those 
entrynames that identify catalog entries that are not volume 
entries. If a volume serial number is specified with the | 
ENTRIES parameter, entrynames of other entry types cannot also 
be specified. However, if the ENTRIES parameter is not — 
specified and if entry types are not specified (that is, 
CLUSTER, SPACE, DATA, and so forth), all entries in the catalog, 
including volume entries, are listed. 
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a 7* LIST ALL CATALOGED INFORMATION FOR EACH ENTRY */ 
LISTCAT - 


ALL - 
CATALOG (MJKCAT) 


LISTING FROM CATALOG -- MJKCAT 


AIX oceeeooe--- MJK.ALT. INDEX) 


HISTORY 

OWNER - IDENT -~------ CNULL} 

RELEASE ----~-~-~-~--~-- 2 
PROTECTION-PSWD----- (NULL) 
ASSOCIATIONS 

DATA----- MJK. ALT. INDEX] .DATA 


INDEX----MJK ALT. INDEX! . INDEX 


CLUSTER--MJK .CLUSTERI 
PATH----- MJK .AIX1 .PATH 


ATTRIBUTES 
UPGRADE 
DATA ------- MJK. ALT. INOEX1.DATA 
HISTORY 
OWNER-IDENT------- (MULL) 
RELEASE---------------- 2 
PROTECTION-PSNO----- (NULL) 
ASSOCIATIONS 
AIX------ MJK .ALT. INDEX 
ATTRIBUTES 
KEYLEN--~-------------- 5 
RK Pewee ewe-ne----=--+-- 5 
AXRKP----------------- 45 
SHROPTNS(1,3) RECOVERY 
UNORDERED NOREUSE 
STATISTICS 
REC-TOTAL-------------- 4 
REC-DELETED------------ 0 
_ REC-INSERTED----------- 0 
es, REC-UPDATED------------ 0 
( REC-RETRIEVED---------- 0 
ALLOCATION 
SPACE-TYPE--------- TRACK 
SPACE-PRI -------------- 6 
SPACE-SEC-------------- 6 
VOLUME 
VOLSER------------ 333001 
DEVTYPE------ X'30502009' 
VOLFLAG------------ PRIME 
EXTENTS: 
LOW-CCHH----- X'00040008' 


HIGH-CCHH----X'00040000° 


Figure 14 (Part 1 of 7). 


CREATION---------- 77.040 
EXPIRATION-------- 00.000 
RACF ---------------- (NO) 
CREATION---------- 77.040 
EXPIRATION------~-- 00.000 
RACF ---------------- (NO) 
AVGLRECL------------ 4086 
MAXLRECL----------- 32600 
SUBALLOC NOERASE 
SPANHED NONUNIQKEY 
SPLITS-CI-------------- 0 
SPLITS-CA-------------~- 0 
FREESPACE-“CI---------- 0 
FREESPACE~/CA-~---------~ 0 
FREESPC-BYTES--~--- 69632 
HI-ALLOC-RBA------- 73728 
HI-USEO-RBA-------- 73728 
PHYREC-SIZE--------- 4096 
PHYRECS/TRK------------ 3 
TRACKS/CA~------------- 6 
LOW-RBA---------------- 0 
HIGH-RBA----------- 73727 


RCVY-VOL---------- 333001 
RCVY-DEVT----X' 30502009° 


RCVY-VOL~<--------- 333001 
RCVY-DEVT----X' 30502009’ 


BUF SPACE~----------- 8704 
EXCPEXIT---------- (NULL) 
INDEXED NOWRITECHK 
EXC PS~--~ ---~------ === 7 
EXTENTS---------------- 1 
SYSTEM-TIMESTANP: 
X*8AS1B6C0C87CF000' 
HI-ALLOC-RBA------~- 73728 
HI-USED-RBA~------- 73728 
TRACKS----------------- 6 


Example of LISTCAT ALL Output 


RCVY-CI-------- X*000010° 
RCVY-CI-------- X*000011' 
CISIZE-------------- 6096 
Cl/Cissvedecececees=s- 16 
NOIMBED NOREPLICAT 
EXTENT-NUMBER---------- 1 
EXTENT-TYPE-------- x00" 





an 
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INDEX ------ MJK.ALT. INDEX1. INDEX 
HISTORY 
OWNER-IDENT------- (NULL) 
RELEASE---------------- 
PROTECTION-PSWD----- (NULL) 
ASSOCIATIONS 
AIX------ MJK.ALT. INDEX] 
ATTRIBUTES 
KEYLEN----- woe--------- 5 
_ RKP-------- eoenn------- 5 
— SHROPTNS(1,3) RECOVERY 
NOREUSE 
STATISTICS 
REC-TOTAL-------------- 1 
REC-DELETED------------ 0 
REC-INSERTED------ o----0 
REC-UPDATED------------ 0. 
REC-RETRIEVED---------- 0 
ALLOCATION 
SPACE-TYPE--------- TRACK 
SPACE-PRI-------------- 1 
SPACE-SEC-------------- 1 
VOLUME | 
VOLSER------------333001 
DEVTYPE------X' 30502009' 
VOLFLAG------------ PRIME 
EXTENTS: 
LOW-CCHH----- X'0004000E' 
HIGH-CCHH----X'0004000E' 
PATH ------- MJK.AIX1. PATH 
HISTORY 
~ OKNER-IDENT~------ (NULL) 
RELEASE---------------- 2 
PROTECTION-PSWD----- (NULL) 
ASSOCIATIONS 
AIX------ MJK.ALT. INDEX! 
DATA----- MJK.ALT. INDEX) .DATA 
INDEX----MJK ALT. INDEX). INDEX 
DATA----- MJK.CLUSTER.DATA 
INDEX----MJK.CLUSTER} . INDEX 
ATTRIBUTES 
UPDATE 
CLUSTER ------- MJK.CLUSTERI 
“HISTORY 
OWNER-IDENT----- OWNCLUST 
RELEASE---------------- 2 
PROTECTION 
MASTERPW---------- MASTCL 
CONTROLPW--------- CNTLCL 
USAR-------------- (NONE ) 
ASSOCIATIONS 


DATA~-----MNJK .CLUSTER] .DATA 
INDEX----MJK.CLUSTER1! . INDEX 


AIX------ MJK.ALT. INDEX] 


Figure 14 (Part 2 of 7). 


CREATION----------77.040 
EXPIRATION---~--~--- 00.000 
RACE on ewww nnn www ne (NO) 
AVGLRECL-----= ewouw ounnmn 
MAXLRECL~----- ween enne 505 
SUBALLOC NOERASE 
SPLITS-CI------------ --0 
SPLITS -CAon meee ew wewwuwnHQ 
FREESPACE-4CI----~----- 0 
FREESPACE-/CA------- -<--0 
FREESPC-BYTES--~----9728 
HI-ALLOC-RBA------- 10240 . 
HI-USED-RBA-~--------- 512 
PHYREC-SIZE---------- 512 
PHYRECS/TRK-------- ---20 
TRACKS/CA---- 2-2 ------- 1 
LOW-RBAanneeddosseases 
HIGH-RBA--~--------- 10239 
CREATION---------- 77.040 
EXPIRATION-------- 00.000 
RACF ---------------- (NO) 
CREATION---------~ 77.040 
EXPIRATION-------- 77.140 
UPDATEPH----------- UPOCL 
READPW- ------- ~~ READCL 


RCVY-VOL----------333001 
RCVY-DEVT----X' 30502009' 


BUF SPACE---~--------~--0 
EXCPEXIT------- ==-(NULL) 
NOWRITECHK NOIMBED 


EXCPS----- wo nen wenn nee 3 

EXTENTS----------- o----] 

SYSTEM-TIMESTAMP: 
X'GA5S1B6COC87CF000' 


HI-ALLOC-RBA-----~-10240 
HI-USED-RBA----------512 


TRACKS -<-<--- owe w wma a 1 


RCVY-VOL ---------- 333001 
RCVY-DEVT~----X* 30502009° 


RCVY-VOL~--~-------333001 
RCVY-DEVT~----X' 30502009" 


Example of LISTCAT ALL Output 


RCVY-CI---~~ ---X'000012' 
CISIZE------------ ~--512 
CI/CA------- eonnn----- 20 
NOREPLICAT UNORDEREO 
INDEX: 

LEVELS--------- we wwewnn 1 
ENTRIES/SECT----------- 4 
SEQ-SET-RBA--~---------- 0 
HI-LEVEL-RBA-------~---- 0 
EXTENT-NUMBER--~------- 1 
EXTENT-TYPE-------- x00" 
RCVY-CI----- ---X'000014' 


RCVY-CI------=--X* 00000E ' 
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DATA ------- MJK.CLUSTER.DATA 

HISTORY 
OWNER-IDENT---~--- (NULL) CREATION~----~-~---- 77.040 RCVY-VOL<-<<<<<---~ 333001 RCVY-CI--------X'00000D' 
RELEASE ~~---~-~-------- 2 EXPIRATION---~-~--- 00.000 RCVY-DEVT-~--X' 30502009' 

PROTECTION-PSWD--~--~ (NULL) RACF --- ~~ 2 ---~ o-oo (NO) 

ASSOCIATIONS 
CLUSTER--MJK.CLUSTER1 

ATTRIBUTES 
KEY LEN-- << - en nen nnn enn 5 AVGLRECL~----- nn nen 80 BUF SPACE --~---~----- 25088 CISIZE~--- eee ene 12288 
RK Pw nnn nn en nnn ne 5 MAXLRECL~-~---~------- 100 EXCPEXIT--~------ EXITCLUS CI/CA monn nnn enon ewsenwe 2 
SHROPTNS(1,3) RECOVERY SUBALLOC NOERASE INDEXED NOWRITECHK NOIMBED NOREPLICAT 
UNORDERED NOREUSE NONSPANNED 

STATISTICS 
REC-TOTAL------------- 20 SPLITS-CIi----~-----~--- 0 EXCP$-<-<<~newnnnneeas= 4 
REC-DELETED~------------ 0 SPLITS-CA-------------- 0 EXTENTS <<< eee ene scenne 1 
REC-INSERTED-~----------- 0 FREESPACE-/CI~-~----~--- 15 SYSTEM-TIMESTAMP: 
REC-UPDATED-~~---------- 0 FREESPACE-ZCA~-------- 20 X'&A51B6ACD5B92000' 
REC-RETRIEVED-------~- 20 FREESPC-BYTES------ 12288 

ALLOCATION 
SPACE-TYPE--~----~- TRACK 
SPACE-PRI-------------- 2 HI-ALLOC-RBA--~----- 24576 
SPACE-SEC---~~---------- 2 HI-USED-RBA-~-~-~----~ 24576 

VOLUME 
VOLSER-~---------- 333001 PHYREC-SIZE--------- 4096 HI-ALLOC-RBA------- 24576 EXTENT-NUMBER---~----~-- i 
DEVTYPE~------ X°30502009' PHYRECS/TRK----<------- 3 HI-USED-RBA-~------ 24576 EXTENT~TYPE-~--~---X'00' 
VOLF LAG~---~-~------- PRIME TRACKS/CAr- <2 2 oe == 2 
EXTENTS: 
LOW-CCHH---~--- X'00040005' LOW-RBA---------------- 0 TRACKS <9 << ee ween ennanwe 2 
HIGH-CCHH----X' 00040006 ' HIGH-RBA-~---------- 24575 

INDEX ~----~ MJK .CLUSTER1 . INDEX 

HISTORY 
OWNER-IDENT-~------ (NULL) CREATION--~-------- 77.040 RCVY-VOLo<<- <n 333001 RCVY -CI-------- X* OOOOO0F * 
RELEASE ---------------- rs EXPIRATION-----~--- 00.000 RCVY-DEVT--~-X' 30502009' 

PROTECTION-PSWD----- (NULL) RACE -2- ween nn erene (NO) 

ASSOCIATIONS 
CLUSTER--MJK.CLUSTER1 

ATTRIBUTES 
KEY LEN-~ 3-2 eee nese n-= 5 AVGLRECL--------------- 0 BUF SPACE ~~~ <3 3 e nnn 0 CISIZE------ ssn ese se 512. 
RK Pon nnn nen een enn wen= 5 MAXLRECL~------------ 505 EXCPEXIT~------=-- EXITCLUS CI/CA----- Sees ee Ses 20 
SHROPTNS(1,3) RECOVERY SUBALLOC NOERASE NOWRITECHK NOIMBED NOREPLICAT UNORDERED 
NOREUSE 

STATISTICS 
REC-TOTAL-------------- 1 SPLITS-CI-~--------- ~--0 EXCPS- nnn nn ene meen en eee 4 INDEX: 
REC-DELETED------------ 0 SPLITS-CA-------~ S letatatatees 0 EXTENTS~-~- nnn ene nnn | LEVE LS --- nn enn n nnn nnn 1 
REC-INSERTED--~-------- 0 FREESPACE-“ZCI--~-----~-- 0 SYSTEM-TIMESTAMP: ENTRIES/SECT----------- 1 
REC-UPDATED------------ 0 FREESPACE-“CA--~~--~---- 0 X°8A51B6ACD5B92000’ SEQ-SET-RBAw-- eo -~---~ 0 
REC-RETRIEVED---------- 0 FREESPC-BYTES----~--- 9728 HI~LEVEL-RBA~---------- 0 

ALLOCATION 
SPACE-TYPE--------- TRACK 
SPACE-PRI-------------- 1 HI-ALLOC-RBA------- 10240 
SPACE-SEC--~--~----~~--- 1 HI-USED-RBA----~------ 512 

VOLUME 
VOLSER---~-------- 333001 PHYREC-SIZE-~---~~----- 512 HI-ALLOC-RBA-----~- 10240 EXTENT-NUMBER~-~--~~---~-~ 1 
DEVTYPE------ X'30502009' PHYRECS/TRK~----~------ 20 HI-USED-RBA-~--~------- 512 _ EXTENT-TYPE-------- X*00’ 
VOLF LAG-----------~ PRIME TRACKS/CA-~----~------- 1 
EXTENTS: 
LOW-CCHH----- X'00040007' LOW-RBA<=-<<<-—<<>e7ss~= 0 TRACKS - 23 << een eee n ne 1 
HIGH-CCHH~---X'00040007" HIGH-RBA--~--------- 10239 

GOG BASE ------ MJK.GDG1 

HISTORY 
OWNER-IDENT------- OWNGDG CREATION------~-~--- 77.940 RCVY-VOL---------- 333001 RCVY-CI -------- X*'000015' 
RE LEASE -------~-- == ~~~ 2 EXPIRATION--~----- 99.365 RCVY-DEVT---~X'30502009' 

ATTRIBUTES 
LIME Too eon een ene owen 250 SCRATCH EMPTY 

ASSOCIATIONS 


NONVSAM--MJK .GOG1 .G0001V00 


Figure 14 (Part 3 of 7). Example of LISTCAT ALL Output 
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NONVSAM ---- MJK.GDG! .G0001V00 





HISTORY 
OWNER-IDENT------- (NULL) CREATION---------- 77.040 RCVY-VOL------~---333001 RCVY-CI----~---- X'000016' 
RELEASE -+-==----+=s==<- 2 EXPIRATION-------- 00.060 RCVY-DEVT~--~-X* 30502009" 
VOLUNES 
VOLSER = <<==s=<e-<¢ 333001 DEVTYPE------ X'39502009' FSEQN=3>SSoSe<8e5eseS o> 0 
VOCSER==-<<255--5= 333002 DEVTYPE------ X'305020093' FSEQN+=s8sseS—8ee ene 0 
ASSCCIATIONS 
GOG------ MJK .GDG1 
ALIAS--~-MJK.GOG1.ALIAS 
ALIAS --------- MJK .GDG1 .ALIAS 
HISTORY 
RELEASE -<---------------- 2 RCVY-VOL---------- 333001 RCVY-DEVT----X' 30502009' RCVY-CI-------- X*000017' 
ASSOCIATIONS 
NONVSAM--MJK .G0G1.G0001V00 
NONVSAM ------- MJK.NONVSAM1 
HISTORY 
OWNER-IDENT------- (NULL) CREATION---------- 77.040 RCVY-VOL-~----<----- 333901 RCVY-CI----- ~--X'000016' 
RELEASE ~-<-<-----9-------- 2 EXPIRATION-----~--- 00.000 RCVY-DEVT----X' 30502009" 
VOLUNES : 
VOLSER<--~--------- 333001 DEVTYPE------ X'30502009° PSEQN e533 <=7ese-sSeer= 0 
ASSOCIATIONS-------- (NULL) 
CLUSTER ------- MJKCAT 
HISTORY 
OWNER-IDENT------- (NULL) CREATION-------~--- 77.040 
RELEASE --- 2-0 ------- = 2 EXPIRATION--~------ 99.999 
PROTECTION-PShD----- (NULL) RACK enn n ee eer err enn= (NO) 
ASSOCIATIONS 
DATA----- VSAM. CATALOG. BASE .DATA.RECORD 


INDEX~----VSAM.CATALOG.BASE .INDEX.RECORD 


Figure 194 (Part 4 of 7). Example of LISTCAT ALL Output 
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HISTORY 
OWNER~IDENT------- (NULL) 
RELEASE ---------------- 2 
PROTECT ION-PSWO----- (NULL) 
ASSOCIATIONS 
CLUSTER--MJKCAT 
ATTRIBUTES 
KEYLEN---------------~- 44 
RKP--- 2-2 e-em enn ene e 0 
SHROPTNS(3,3) RECOVERY 
UNORDERED NOREUSE 
STATISTICS 
REC-TOTAL~------------- 15 
REC-DELETED------------ 0 
REC-INSERTED----------- 0 
REC-UPDATED------------ 0 
REC-RETRIEVED---------- 0 
ALLOCATION 
SPACE~-TYPE--------- TRACK 
SPACE -PRI------------- 57 
SPACE ~SEC-----~-------- 18 
VOLUME 
VOLSER<---2-----~-- 333001 
DEVTYPE------ X*30502009' 
VOLF LAG~----------- PRIME 
LOW-KE Yon n nnn nn ene nn-- 00 
HIGH-KEY-~------------ 3F 
HI-KEY-RBA---------- 6144 
EXTENTS: 
LOW-CCHH----- X*00000002' 
HIGH-CCHH~---X'00020011' 
VOLUME 
VOLSER---~<------- 333001 
DEVTYPE------ X*30502009' 
VOLF LAG~----------- PRINE 
LON-KE Yoee enn n nnn none 40 
HIGH-KEY-~------------- FF 
HI-KEY-RBA-------- 368640 
EXTENTS: 
LOW-CCHH----- X*00030002' 


HIGH-CCHH----X‘'00030004' 


Figure 14 (Part 5 of 7). 


CREATICN---------- 00.000 
EXPIRATION-------- 00.000 
RACF~--------------- (NO) 
AVGLRECL------------- 505 
MAXLRECL------------- 505 
SUBALLOC NOERASE 
NONSPANNED BIND 
SPLITS-CI-------------- 0 
SPLITS-CA-------------- 0 
FREESPACE-/CI---------- 0 
FREESPACE-/CA-~-------- 0 
FREESPC-BYTES----- 381952 
HI-ALLOC-RBA------ 389120 
HI-USED-RBA------- 389120 
PHYREC-SIZE---------- 512 
PHYRECS/TRK ----------- 20 
TRACKS/CA-------------- 3 
LOW-RBA----~------------ 0 
HIGH-RBA---------- 368639 
PHYREC-SIZE-------- -- 512 
PHYRECS/TRK----------- 20 
TRACKS/CA-------------- 3 
LOW-RBA----------- 368640 
HIGH-RBA---------- 389119 








BUF SPACE------------ 3072 
EXCPEXIT---------- (NULL) 
INDEXED NOKRITECHK 
RECVABLE 

EXCPS----------------- 24 
EXTENTS---------------- 2 


SYSTEM-TINESTAMP: 
X'8A51686244C1B1000' 


HI-ALLOC-RBA---~---- 368640 
HI-USED-RBA-----~--- 20480 
TRACKS---------------- 54 
HI-ALLOC-RBA-~----- 389120 
HI-USED-RBA------- 389120 
TRACKS~----------------- 3 


Example of LISTCAT ALL Output 


Appendix A. 





CISIZE-~-------------- 512 
CI/CA--------- ~~~ - ~~ + 40 
IMSED NOREPLICAT 
EXTENT-NUMBER---~------ 1 
EXTENT-TYPE---~--~-~ X'00! 
EXTENT-NUMBER-~---~------- 1 
EXTENT-TYPE-------- X'00! 
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INDEX ------ VSAM. CATALOG.BASE .INDEX.RECORD 
HISTORY 
OWNER-IDENT~------- (NULL) CREATION-~--------- 00.000 
RELEASE ----------------2 EXPIRATION-------- 60.000 
PROTECTION-PSWD----- (NULL) RACF --0<---2-------- (HO) 
ASSOCIATIONS 
CLUSTER--MJKCAT 
ATTRIBUTES . 
KEY LEN----9----------- 44 AVGLRECL--------------- 0 
RK Pw nm nn enn ne nen ene 0 MAXLROICL------------- 505 
SHROPTNS( 3,3) RECOVERY SUSALLOC NOERASE 
NOREUSE BIND 
STATISTICS 
REC-TOTAL-------------- 3 SPLITS-CI-------------- 0 
REC-ODELETEO------------ 0 SPLITS-CA-------------- 0 
REC-INSER TEO----------- 0 FREESPACE-¢4CI---------- 0 
REC-UPDATED------------ 0 FREESPACE-“.CA---------- 0 
REC-RETRIEVED---------- 0 FREESPC-BYTES------ 38912 
ALLOCATION 
SPACE-TYPE--------- TRACK 
SPACE-PRI -------------- 3 HI-ALLOC-RBA------- 40448 
SPACE -SEC-------------- 3 HI-USED-RBA-~------ 40448 
VOLUME 
VOLSER------------ 333001 PHYREC-SIZE---------- 512 
DEVTYPE~----- X'30502009' PHYRECS/TRK--<--------- 20 
VOLF LAG------------ PRIME TRACKS/CA-------------- 1 
EXTENTS: 
LOW-CCHH----- X'00020012' LOW-RBA----------<----- 0 
HIGH-CCHH----X'00030001' HIGH-RBA----------- 30719 
VOLUME 
VOLSER------------ 333001 PHYPEC-SIZE---------- 512 
DEVTYPE------ X'30502009' FHYRECS/TRK----------- 20 
VOLF LAG------------ PRINE TRACKS/CA- ---- << -- n-ne - 3 
LOW-KE Y--------------- 00 
HIGH-KEY-------------- 3F 
EXTENTS: 
- LOW-CCHH----- %*00000002° LCW-RBA------------ 30720 
HIGH-CCHH--~--X‘'00020011' HIGH-RBA----------- 39935 
VOLUME 
VOLSER~------------ 333001 PHYREC-SIZE---------- 512 
DEVTYPE------ X*30502009° PHYRECS/TRK----------- 20 
VOLF LAG------------ PRIME TRACKS/CA--- 9-9 ------- 3 
LOW-KEY --------------- 40 
HIGH-KEY -------------- FF 
EXTENTS: 
LOW-CCHH----- X*'00030002' LOW-RBA------------ 39936 
HIGH-CCHH----X'00030004' HIGH-RBA-----~----- 10447 


Figure 14 CPart 6 of 7). 


BUF SPACE--------------- 0 
EXCPEXIT---------- (NULL) 
NO} !RITECHK INSEO 
EXCPS--~-------------- 13 
EXTENTS ---------------- 3 
SYSTEM-TIMESTAMP: 


X'8A5186244C1B1009' 


HI-ALLOC-RBA~------ 30720 
HI-USED-RBA--<-------- 612 
TRACK S---- - oo eo wn nee ne 3 
HI-ALLOC-RBA------=- 39936 
HI-USED-RBA-~------- 31232 
TRACKS ~ 2 www on wn ew ee ewe 54 
HI-ALLOC-RBA------- 40448 
HI-USED-RBA-------- 40448 
TRACKS ~~ 2 - ene enw eww ene 3 


Example of LISTCAT ALL Output 
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CISIZE cae wewowwoaeee 512 
CI/CA <> om Gm GD oe ow OF OD OD GF OD Ow Oe Oe Oo we Ka () 
NCREPLICAT UNORDERED 
INDEX: 

LEVELS ------ ~~~ oo oo ee 2 
ENTRIES/SECT----------- 7 
SEQ-SET-RBA-------- 30720 
HI-LEVEL-RBA----------- 0 
EXTENT -NUMBER---------- 1 
EXTENT-TYPE-------- X'00' 
EXTENT-NUMBER~---------- 1 
EXTENT-TYPE-------- x' 80° 

\ 

EXTENT-NUMBSER---------- 1 
EXTENT~TYPE-------- x80! 





























VOLUME -------- 333001 
HISTORY 
RELEASE---------------- 2 RCVY-VOL-~--------- 333001 RCVY-DEVT----X' 30502009' RCVY-CI------ ~-X'0000699" 
CHARACTERISTICS | 
BYTES/TRK---------- 13165 DEVTYPE------ x'30502009° MAX-PHYREC-SZ------13030 DATASETS-ON-VOL---~----- 5 
TRKS/CYL--------------- 19 VOLUME- TIMESTAMP: MAX-EXI/ALLOC---------- 5 DATASPCS-ON-VOL-------- L 
CYLS/VOL------------- 411 X'8A51B6A76850E000' 
DATASPACE 
DATASETS--------------- 5 FORMAT-1-DSCB: ATTRIBUTES: 
EXTENTS---------------- 1 CCHHR------ X'0000000103' SUBALLOC 
SEC-ALLOC------------- 40 TIMESTAMP EXPLICIT 
TYPE--~-~----~~---- TRACK X'8A51B61D97B04000' USERCAT 
EXTENT-DESCRIPTOR: 
TRACKS-TOTAL--------- 160 BEG-CCHH----- X'00000002' SPACE-MAP----------- 5947 
TRACKS -USEO-----------99 
DATASET-DIRECTORY: 
OSN----MJKCAT ATTRIBUTES-------- (NULL) EXTENTS---~------------- 3 
DSN----MJK.CLUSTER.DATA ATTRIBUTES-------- (NULL) EXTENTS---------------- i 
OSN----MJK CLUSTER. INDEX ATTRIBUTES-------- (NULL) EXTENTS------ a-~------- \ 
OSN----MJK.ALT. INDEX! .DATA ATTRIBUTES-------- (NULL) EXTENTS~-~------------- i 
OSN----MJK .ALT. INDEX1. INDEX ATTRIBUTES-------- (NULL) EXTENTS---~------------ i 
LISTING FROM CATALOG -- MJKCAT 
THE NUMBER OF ENTRIES PROCESSED WAS: 
AIX ---+-~------------- 1 
ALIAS o22oSehes-ceccos: 1 
CLUSTER --------------- 2 
DATA -~--~------------- 3 
GDG ------------------- 1 
INDEX ----------------- 3 
NONVSAM --------------- 2 
PAGESPACE ------------- 0 
PATH -+--+~=-=---------- 1 
SPACE ----------------- 1 
USERCATALOG ----------- 0 
TOTAL ---------------- 15 
( THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 





IOCOOO1I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 


IOCOO0O02E IOCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 


Figure 14 (Part 7 of 7). Example of LISTCAT ALL Output 
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LISTCAT ALLOCATION OUTPUT LISTING 


When you specify the LISTCAT command and include the ALLOCATION ae 
parameter, each cataloged object with space allocated to it from \ es 
a VSAM data space is listed (see Figure 15). All information 
about the object's space is listed, but none of the object's 
other cataloged information is listed. The entry types that can 
be specified when the ALLOCATION parameter is specified are 
limited to DATA and INDEX. 











7* LIST SPACE ALLOCATION INFORMATION */ 


LISTCAT - 
ALLOCATION - 
CATALOG(MJKCAT) 
| 
| AIX ----------- MJK ALT. INDEX} 
HISTORY 
OWHER-IDENT------- (NULL) CREATION---------~ 77.040 RCVY-VOL---------- 333001 RCVY-CI--------X'000010' 
RELEASE---------------- 2 EXPIRATION-------- 00.000 RCVY-DEVT----X' 30502009' 
DATA ------- MJK.ALT.INOEX1 DATA 
HISTORY 
OWNER-IDENT------- (NULL) CREATION---------- 77.040 RCVY-VOL---------- 333001 RCVY-CI----- ---X'000011" 
RELEASE---------------- 2 EXPIRATION-------- 00.000 RCVY-DEVT----X' 30502009° 
ALLOCATION 
SPACE-TYPE--------- TRACK 
SPACE-PRI-------------- 6 HI-ALLOC-RBA------- 73728 
SPACE-SEC-------------- 6 HI-USED-RBA-------- 73728 
VOLUME 
VOLSER------------ 333001 PHYREC-SIZE--~------- 4096 HI-ALLOC-RBA------- 73728 EXTENT-NUMBER-----~----1 
DEVTYPE------ X'30502009' PHYRECS/TRK------------ 3 HI-USED-RBA-------- 73728 EXTENT-TYPE-------- X'00' 
VOLFLAG------------ PRIME TRACKS/CA-------------- 6 
EXTENTS: 
LOW-CCHH----- X*00040008' LOW-RBA-----------~----- 0 TRACKS----------------- 6 
HIGH-CCHH----X' 00040000". HIGH-RBA----------- 73727 
INDEX ------ MJK. ALT. INDEX1. INDEX Re 
HISTORY 
OWNER- IDENT------- (NULL) CREATION---------- 77.040 RCVY-VOL---------- 333001 RCVY-CI-------- X*000012' 
RELEASE---------------- 2 EXPIRATION-------- 00.000 RCVY-DEVT----X' 30502009' 
ALLOCATION 
SPACE-TYPE--------- TRACK 
SPACE-PRI-------------- 1 HI-ALLOC-RBA------- 10240 
SPACE-SEC-------------- 1 HI-USED-RBA---------- 512 
VOLUME 
VOLSER-~---------- 333001 PHYREC-SIZE---------- 512 HI-ALLOC-RBA------- 10240 EXTENT-NUMBER----------1 
DEVTYPE------ X*30502009' PHYRECS/TRK~----------- 20 HI-USED-RBA---------- 512 EXTENT-TYPE--------X'40' 
VOLFLAG------------ PRIME TRACKS/CA-------------- 1 
EXTENTS: | 
LOW-CCHH----- X'0004000E' LON-RBA---------------- 0 TRACKS----------------- 1 
HIGH-CCHH----X'0004000E' HIGH-RBA----------- 10239 
PATH ------- MJK.AIXL.PATH 
HISTORY 
OWNER-IDENT------- (NULL) CREATION-------~-- 77.040 RCVY-VOL---------- 333001 RCVY-CI------- -X%'000014' 
RELEASE---------------- 2 EXPIRATION-------- 00.000 RCVY-DEVT----X' 30502009' 
CLUSTER ------- MJK.CLUSTERI 
HISTORY 
OWNER-IDENT----- OWNCLUST CREATION---------- 77.040 RCVY-VOL---------- 333001 RCVY-CI~--------X' 00000E° 
RELEASE ---------------- 2 EXPIRATION-------- 77.040 RCVY-DEVT----X' 30502009' 


Figure 15 (Part 1 of 3). Example of LISTCAT ALLOCATION Output 
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CREATION--~-------- 77.040 
EXPIRATION-------- 00.000 
HI-ALLOC-RBA------- 24576 
HI-USED-RBA-------- 24576 
PHYREC-SIZE--------- 6144 
PHYRECS/TRK--~--------- 2 
TRACKS/CA-------------- 2 
LOW-RBA---------------- 0 
HIGH-RBA----------- 24575 
CREATION---------- 77.040 
EXPIRATION-------- 00.000 
HI-ALLOC-RBA------- 10240 
HI-USED-RBA------- ~--512 
PHYREC-SIZE---------- 512 
PHYRECS/TRK~---------- 20 
TRACKS/CA----~--------- 1 
LOW-RBA---------------- 

HIGH-RBA----------- 10239 
CREATION-~-------- 77.040 
EXPIRATION-------- 99.999 


HISTORY 
OWNER-IDENT------- (NULL) 
RELEASE---------------- 
ALLOCATION 
SPACE-TYPE--------- TRACK 
SPACE-PRI-------------- 2 
SPACE-SEC-------------- 2 
VOLUME 
VOLSER--------- ---333001 
DEVTYPE------ X'30502009' 
VOLFLAG----------~- PRIME 
EXTENTS: 
LOW-CCHH----- X'00040005' 
HIGH-CCHH----X‘00040006' 
INDEX ----- - MJK.CLUSTER] . INDEX 
HISTORY 
OWNER-IDENT------- (NULL) 
RELEASE---------------- 2 
ALLOCATION 
SPACE-TYPE--------- TRACK 
SPACE-PRI-------------- 1 
SPACE-SEC-------------- 1 
VOLUME 
VOLSER------------ 333001 
DEVTYPE------X' 30502009 
VOLFLAG------------ PRIME 
EXTENTS: 
LON-CCHH----- X'00040007' 
HIGH-CCHH----X' 00040007' 
CLUSTER ------- MJKCAT 
HISTORY 
OWNER-IDENT------- (NULL) 
RELEASE---------------- 2 
DATA ------- VSAM. CATALOG.BASE.OATA.RECORO 
HISTORY 
an OWNER-IDENT------- (NULL) 
( RELEASE---------------- 2 
ALLOCATION 
SPACE-TYPE--------- TRACK 
SPACE-PRI------------- 57 
SPACE-SEC------------- 18 
VOLUME 
VOLSER------------ 333001 
DEVTYPE------X' 30502009 
VOLF LAG------------ PRIME 
LOW-KEY--------------- 00 
HIGH-KEY-------------- 3F 
_HI-KEY-RBA---------- 6144 
EXTENTS: 


LOW-CCHH---~--- X°00000002° 
HIGH-CCHH----X'00020011° 


VOLUME 

VOLSER------------ 333001 
DEVTYPE------ X°30502009' 
VOLF LAG------------PRIME 
LOW-KEY ---------------40 
HIGH -KE Yennn nnn ee om- FF 
HI-KEY-RBA-------- 368640 
EXTENTS: 


LOW-CCHH----- X°00030002' 
HIGH-CCHH----X'00030004' 


Figure 15 (Part 2 of 3). 





A 


CREATION----------00.000 
EXPIRATION------ --00.000 
HI-ALLOC-RBA------ 369120 
HI-USED-RBA------- 389120 
PHYREC-SIZE---------- 512 
PHYRECS/TRK--~-------- 20 
TRACKS/CA-------------- 3 
LOW-RBA------~--------- 0 
HIGH-RBA---------- 368639 
PHYREC-SIZE--~------- 512 
PHYRECS/TRK--~----~--- 20 
TRACKS/CA----~--------- 3 
LOW-RBA----------- 368640 
HIGH-RBA---------- 389119 








RCVY-VOL---------- 333001 
RCVY-DEVT----X' 30502009" 


HI-ALLOC-RBA------- 24576 
HI-USED-RBA--~----- 24576 
TRACKS ------ own ween eee 2 
RCVY-VOL---------- 333001 


RCVY-DEVT~----X'30502009' 


HI-ALLOC-RBA--~----- 10240 
HI-USED-RBA---------- 512 
TRACKS << - nnn mone own eee 1 
HI-ALLOC-RBA-~----- 368640 
HI-USED-RSA-------- 20480 
TRACK S------ 22-2 --- <= 54 
HI-ALLOC-RBA-~---- 389120 
HI-USED-RBA------- 389120 
TRACK$§--- 2-2-2 eee ene 3 


Example of LISTCAT ALLOCATION Output 


Appendix A. 


RCVY-CI-------- X'00000D' 
EXTENT-NUMBER~--------- 1 
EXTENT-TYPE-------- x00" 
RCVY-CI-------- X*0O000F' 
EXTENT-NUMBER~---------- 1 
EXTENT-TYPE-------- x00! 
EXTENT-NUMBER~---------- 1 
EXTENT-TYPE-------- X00! 
EXTENT-NUMBER---------- 1 
EXTENT-TYPE-------- X'00' 


Interpreting LISTCAT Output Listings 293 























HISTORY 
OWNER-IDENT------- (NULL) CREATION---------- 00.000 
RELEASE---------------- 2 EXPIRATION--------00.000 
ALLOCATION | 
SPACE-TYPE--------- TRACK 
SPACE-PRI-------------- 3 HI-ALLOC-RBA------- 40448 
SPACE-SEC-------------- 3 HI-USED-RBA-------- 40448 
VOLUNE | 
VOLSER---------~-- 333001 PHYREC-SIZE---------- 512 HI-ALLOC-RBA-------30720 EXTENT -NUMBER---------- 1 
DEVTYPE------ X*30502009' PHYRECS/TRK----------- 20 HI-USED-RBA----------- 512 EXTENT-TYPE-------~ x°00' 
VOLF LAG------------ PRIME TRACKS/CA-------------- 3 | 
EXTENTS: 
LOW-CCHH----- X*00020012' LOW-RBA---------------- 0 TRACKS----------------- 3 
HIGH-CCHH----X' 00030001" HICH-RBA----------- 30719 
VOLUME 
VOLSER------------ 333001 PHYREC-SIZE---------- 512 HI-ALLCC-PBA------~- 39936 EXTENT-NUMBER---------- 1 
DEVTYPE------ X* 30502009! PHYRECS/TRK----------- 20 HI-USED-FBA-------- 31232 EXTENT-TYPE-------- X'80' 
VOLF LAG------------ PRIME TRACKS/CA-------------- 3 
LOW-KEY--------------- 09 | 
HIGH-KEY-------------- 3F 
EXTENTS: 
LOW-CCHH----- X'00000002' LOW-RBA--------- ~-~39720 TRACKS---------------- 54 
HIGH-CCHH----X'00020011' HIGH-RBA----------- 39935 
VOLUME 
VOLSER----~------- 333001 PHYREC-SIZE---------- 512 HI-ALLOC-RBA------- 40448 EXTENT-NUMBER---------- 1 
DEVTYPE------x' 30502009! PHYRECS/TRK----------- 20 HI-USED-RBA-~------- 40446 EXTENT-TYPE-----~-- X'80' 
VOLF LAG-~~--------- PRIME TRACKS/CA-------------- 3 
LOW-KEY --------------- 40 
HIGH-KEY--~------------- FF 
EXTENTS: 
LOW-CCHH----- X'00030002' LOW-RBA-----~------- 39936 TRACKS----------------- 3 
HIGH-CCHH----X'00030004' HIGH-RBA---------- ~40447 


LISTING FROM CATALOG -- MJKCAT 


THE NUMBER OF ENTRIES PROCESSED WAS: 


AIX ------------------- 1 a 
ALIAS ----------------- 0 
CLUSTER --------------- 2 _Y 
DATA ------------------ 3 
G0G ------------------- 0 

INDEX ----------------- 3 

NCNVSAM --------------- 0 

PAGESPACE ------------- 0 

PATH ------------------ 1 

SPACE ----------------- 0 

USERCATALOG ----------- 0 

TOTAL ---------------- 10 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 
IDCO001I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 
IDC0002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 


Figure 15 (Part 3 of 3). Example of LISTCAT ALLOCATION Output 
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LISTCAT HISTORY OUTPUT LISTING 


When you specify the LISTCAT command and include the HISTORY 
parameter, only the name, ownerid, creation date, and expiration 
date are listed for each entry that is selected (see Figure 16). 
Only these types of entries have HISTORY information: 








Figure 16 (Part 1 of 2). 


Example of LISTCAT HISTORY Output 


Appendix A. 


Interpreting LISTCAT Output Listings 


ALTERNATEINDEX, CLUSTER, DATA, INDEX, NONVSAM, and PATH. 
/* LIST HISTORY INFORMATION FOR EACH ENTRY *#/ 
LISTCAT - 
HISTORY - 
CATALOG(MJKCAT } 
LISTING FROM CATALOG -- MJKCAT 
AIX ener enesen- MJK .ALT. INDEX] 
HISTORY 
OWNER-IDENT-------~ (NULL) CREATION---------- 77.040 RCVY-VOL---------- 333001 RCVY-CI-<------- X'000010' 
RELEASE ~~ -- 22 <n o-oo 2 EXPIRATION-------- 00.000 RCVY-DEVT----X'30502009' 
DATA ------- MJK.ALT.INOEX1 .DATA 
HISTORY 
OWNER-IDENT------- (NULL) CREATION---------- 77.040 RCVY-VOL---~---~----- 333001 RCVY-CI-------- X'00001L' 
RELEASE ---- 2-2-2 << ------ 2 EXPIRATION-------- 00.000 RCVY-DEVT----X'30502609' 
INDEX ------ MJK.ALT.INOEX1 . INDEX 
HISTORY 
OWNER-IDENT-------~ (NULL) CREATION---------- 77.040 RCVY-VOL---------- 333001 RCVY-CI-------- X*000012' 
RELEASE---------------- 2 EXPIRATION-------- 00.000 RCVY-DEVT----X'30502009' 
PATH ------- MJK .AIX1 PATH 
HISTORY 
OWNER -IDENT------- (NULL) CREATION---------- 77.040 RCVY-VOL--------~-- 333001 RCVY-CI----~---- X*'C000014° 
RELEASE ---------------- 2 EXPIRATION-------- 00.000 RCVY-DEVT----X'30502009' 
( CLUSTER ------- MJK .CLUSTER} 
; HISTORY 
OWNER-IDENT----- OWNC LUST CREATION---------- 77.040 RCVY-VOL---------- 333001 RCVY-CI-------- X*OO000E' 
RELEASE---------------- 2 EXPIRATION-------- 77.140 RCVY-DEVT----X'30502009' 
DATA ------- MJK.CLUSTER .DATA 
HISTORY 
OWNER-IDENT------- (NULL) CREATION---------- 77.040 RCVY-VOL-~-------- 333001 RCVY-CI-------- X'000000° 
RELEASE ----<------------ 2 EXPIRATION-------- 00.000 RCVY-DEVT-~---X'30502009' 
INDEX ------ MJK .CLUSTER! . INDEX 
HISTORY 
OWNER-IDENT~------ (NULL) CPEATION---------- 77.040 RCVY=VOL-<---<-5=< 333001 RCVY-Cl-~------- X*'OOO00F' 
RELEASE+<<-<-+essss<e<- 2 EXPIPATION-------- 00.900 RCVY-DEVT-~---X' 20502009" 
GOG BASE -~----- MJK.GOGI 
HISTORY 
OWNER-IDENT-~-~----- OWNGDG CREATION---------- 75.223 RCVY-VOL-----<---~- 333001 ROVY -CI-<<e<<-< X'000015° 
RE LEASE ---------------- 2 EXPIRATION-------- 99.365 RCVY-DEVT----X' 30502009’ 
NONVSAM ---- MJK.GDG1.GO0001V00 
HISTORY 
OWNER-IDENT------- (HULL) CREATION---------- 77.040 RCVY=VOL=+-5--=-5- 333001 RCVY-CI-------- X'000016' 
RELEASE<<s<<eses=-=< 55> 2 EXPIRATION-------- 00.000 RCVY-DEVT----X* 30562009" 
ALIAS --------- MJK.GDGI.ALIAS 
HISTORY 
RELEASE ~----~----------- 2 RCVY-VOL---------- 333001 RCVY-DEVT---~-X' 30502009 RCVY-CI-------- X'000017' 
NONVSAM ------- MJK .NONVSAM1 
HISTORY 
OWNER -IOENT------- (NULL) CREATION----------- 77.040 RCVY-VOL----~------ 333001 RCVY-CI-------- X*000018' 
RELEASE ----~----------- 2 EXPIRATION-------- 00.000 RCVY-DEVT----X'30592009° 
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CLUSTER ------- MJKCAT 


HISTORY 
OWNER-IDENT------- (NULL) CREATION---------- 77.040 
RELEASE-----~- o-+------ 2 EXPIRATION-------- 99.999 
DATA ------- VSAM. CATALOG. BASE .DATA. RECORD 
HISTORY 
OWNER-IDENT------- (NULL) CREATICN---------- 00.000 
RELEASE ---------------- 2 EXPIRATICN-------- 00.000 
INDEX ------ VSAM. CATALOG .BASE . INDEX. RECORD 
HISTORY 
OWNER-IDENT------- (NULL) CREATION---------- 00.000 
RELEASE ---------------- 2 EXPIRATION-------- 00.000 
VOLUME -------- 333001 
HISTORY 
RELEASE---------------- 2 RCVY-VOL---------- 333001 


LISTING FROM CATALOG -- MJKCAT 


THE NUMBER OF ENTRIES PROCESSED WAS: 


AIX ------------------- 1 
ALIAS ----------------- l 
CLUSTER --------------- 2 
DATA ------------------ 3 
G0G ------------------- 1 
INDEX ----------------- 3 
NONVSAM --------------- 2 
PAGESPACE - ------------ 0 
PATH ------------------ 1 
SPACE ----------------- 1 
USERCATALOG ----------- 0 
TOTAL ---------------- 15 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 
IOCOOOLI FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 


IDCOO02I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 


Figure 16 (Part 2 of 2). Example of LISTCAT 





RCVY-DEVT--~-X' 30502009° 


HISTORY Output 
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RCVY-CI 





X*000009" 




















LISTCAT CREATION/EXPIRATION OUTPUT LISTING 


When you specify the LISTCAT command and include the CREATION or 
EXPIRATION parameter Cor both), entries that have a creation or 
expiration date are selected according to the number of days you 
specify in the subparameter. 





In Figure 17, for example, because all entries in the listed 
catalog, USERCAT3, were created on the same day as the LISTCAT, 
no entries are listed as a result of the LISTCAT CREATIONC5) 
job. When that job is run on an older catalog, each entry whose 
creation date is prior to the number of days specified with the 
CREATION parameter is listed (that is, the CREATION number of 
days specifies that all objects in the catalog at least 5 days 
old are to be listed). The creation date of the data and index 
objects of a cluster or alternate index is always the same as 
the creation date of its associated cluster or alternate index 
object. The creation date of the data and index object of a 
catalog is always set to 0 








When you list all entries of a catalog, and you specify the 
CREATION parameter, each user catalog connector entry and each 
alias entry are also listed regardless of their creation date. 


When the LISTCAT EXPIRATIONC20) job is run, each entry whose 
expiration date occurs within 20 days of today's date is listed. 
Because the expiration date of a cluster or alternate index is 
controlled by the cluster or alternate index object entry in the 
catalog, the expiration date for the data and index objects of a 
cluster or alternate index is always 0. 


When you list all entries of a catalog and you specify the 
EXPIRATION parameter, each volume entry will be listed, because 
volume entries have no expiration date. 


a These types of entries can have a creation or expiration date: 
( ALTERNATEINDEX, PATH, CLUSTER, DATA, INDEX, NONVSAM, GDG, and 
PAGESPACE. 
1% LIST EACH CATALOG ENTRY WHOSE CREATION DATE x/ 
7% IS 5 DAYS AGO OR GREATER CTHAT IS, THE OBJECT xX/ 
/*® IS AT LEAST 5 DAYS OLD). X/ 
LISTCAT - 
CREATION(C5) - 
CATALOGCMJKCAT) 
LISTING FROM CATALOG -- MJKCAT 
ALIAS --3------ MJK.GDG1.ALIAS 


Figure 17 (Part 1 of 2). Example of LISTCAT CREATION/EXPIRATION Output 
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_ LISTING FROM CATALOG ~~ USERCATS 
THE pan ENTRIES PROCESSED WAS: | 


ne on dest te ee ee GE enue cts Get Gan CE CE One Gee Gm CED me em 


ALIAS ----------------- 1 
CLUSTER --------------- 0 
DATA ------------------ 0 
GDG ------------------- 0 
INDEX ----------------- 0 
NONVSAM --------------- 0 
PAGESPACE ----~-------- 0 
PATH ~----------------- 0 

— ----------------- 0 
USERCATALOG ----------- 0 
TOTAL ----------------- 1 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 
IDCOO0O1IT FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 


/% LIST EACH CATALOG ENTRY WHOSE EXPIRATION DATE X/ 
/¥ IS WITHIN 20 DAYSX/ 


LISTCAT - 
EXPIRATIONC20) - 
CATALOGCMJKCAT ) 


LISTING FROM CATALOG -- USERCATS 


AIX ----------- MJK.ALT.INDEX1 
DATA ------~ MJK.ALT.INDEX1.DATA 
INDEX ~---~~ MJK. ALT. INDEX1 . INDEX 
PATH ------- MJK.AIX1.PATH 

ALIAS ----~---- MJK.GDG1.ALIAS 

NONVSAM ----~-- MJK. NONVSAMI 

VOLUME ~------- 333001 


LISTING FROM CATALOG ~~ USERCATS 
THE dat ae ENTRIES PROCESSED WAS: 


ALIAS ----------------- 1 
CLUSTER --------------- 0 
DATA -~---------------- 1 
GDG ------------------- 0 
INDEX ----------------- 1 
NONVSAM ~-------------- 1 
PAGESPACE ------------- 0 
PATH ~----------------- 1 

PACE ----------------- 1 
USERCATALOG ----~~~7~-~ 0 


THE NUMBER OF PROTECTED ENTRIES SUPPRESSED WAS 0 
IDCOOOLI FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 
IDCOO002I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 
Figure 17 (Part 2 of 2). Example of LISTCAT CREATION/EXPIRATION Output 
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EXAMPLES OF LISTCAT IN A TSO ENVIRONMENT 


The following examples illustrate the output produced at a TSO 
terminal for a LISTCAT NAMES Cdefault) and LISTCAT VOLUME. A 
TSO logon ID of IBMUSER is assumed. 


For LISTCAT NAMES, the catalog name is printed, followed by the 
names of all entries that have a high-level qualifier equal to 
the USER logon ID. 


For LISTCAT VOLUME, all entrynames that have a high-level 
qualifier equal to the USER logon ID are printed, followed by 
the volume serial numbers for those entries that contain volume 
information. 


Note: Because volume serial numbers for a cluster or an 
alternate index are contained in the data and index components, 
the data and index must have been named on the initial DEFINE in 
order to list the volume serial numbers. 


LOGON IBMUSER 


READY 
LISTCAT 


IN CATALOG: AMASTI 
IBMUSER.AIX 
IBMUSER.AIXDATA 
IBMUSER.AIXIDX 
IBMUSER.GDG 
IBMUSER.GDG.G0001V00 
IBMUSER.GDG.GO002V00 
IBMUSER.GDG.G0003V00 
IBMUSER.KSDS 
IBMUSER.KSDSDATA 
IBMUSER.KSDSIDX 
IBMUSER.NVSAM1 
IBMUSER.NVSAM2 
IBMUSER.NVSAM3 
IBMUSER.NVSAM4 
IBMUSER.NVSAM5 

READY 


LISTCAT VOLUME — 


IBMUSER.AIX 
IBMUSER.AIXDATA 
-~VOLUMES-- 
333001 
IBMUSER.AIXIDX 
-~-VOLUMES-- 
333001 
IBMUSER.GDG 
IBMUSER.GDG.G0001V00 
--VOLUMES-- 
333001 
333002 


333003 
IBMUSER.GDG.G0002V00 
~-VOLUMES-- 
333004 
333005 
333006 
333007 


333008 
abl Fy hae .G0003V00 
333009 
333010 
IBMUSER.KSDS 
IBMUSER.KSDSDATA 
-~-VOLUMES-- 
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333001 
IBMUSER . KSDSIDX 
--VOLUMES-- 
333001 
IBMUSER.NVSAMI 
~-VOLUMES-- 

333001 
333002 
IBMUSER .NVSAM2 
~-VOLUMES-- 
333003 
333004 
333005 


IBMUSER.NVSAM3 
~-VOLUMES-~ 
333006 
IBMUSER.NVSAM4 
~-VOLUMES-- 


333007 

IBMUSER.NVSAM5 
~-VOLUMES~-- 

333008 

333009 

333010 

333011 

333012 
READY 
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When you code the LISTCRA command, you can specify options that 
allow you to tailor the contents of the LISTCRA output. This 
appendix illustrates the various types of LISTCRA output, the 
order in which entries are listed, and the meanings of the 
listed fields. 


There are five kinds of LISTCRA listings. Four are illustrated 

in this appendix; the fifth, SEQUENTIALDUMP, is the same as that 
for DUMP NOCOMPARE, except that the entries are not sorted into 

groups. 


Each listed entry is identified by type (that is, by cluster, 
non-VSAM, and so on) and by name. Entries are usually listed in 
alphabetic order within groups of entries, according to 
entryname Cexcept for SEQUENTIALDUMP). However, if insufficient 
virtual storage is available for the sorting operation, the 
records are listed as they appear in the catalog recovery area. 


On the listing, entries are sorted into three groups Cexcept for 
a SEQUENTIALDUMP listing): 


° VSAM entries Cwhich are also sorted according to entryname). 
Cluster entries, alternate index entries, and their 
associated data, index, and path entries are within this 
group. 


e Other entries that are sorted according to entryname. User 
catalog connector entries and non-VSAM entries are in this 
group. 


6 Unsorted entries: other entries that are not sorted 
according to entryname. Entries that are listed within this 
group depend on the type of LISTCRA listing requested. 


The following list contains the abbreviation, type, and 
description for each Kind of entry that can be listed as a 
result of the LISTCRA command: 


Abbreviation Type Description 


AIX G Alternate index entry 

ALIA X Alias entry 

CLUS C Cluster entry _ 

DATA D Data component entry 

FRSP F Freespace entry 

GDGB B Generation data group entry 

INDX I Index component entry 

NONV A Non-VSAM data set entry 

OEXT E Extension record for an entry other than 
a volume entry 

PATH P Path entry 

UCAT U User catalog connector entry (Cin the 
master catalog only) 

UPGD Y Upgrade set entry 
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Abbreviation Type “Peseripeioa 


~ VEXT W _ Extension record for a volume entry 
VOL V Volume entry 
| 
The five kinds of LISTCRA listings are: 


NAME NOCOMPARE—This is the default option. Each entryname, 


its volumes, and the name and volumes of each related entry 
are listed. Within the "unsorted entries" group, all 
catalog records not yet Pranced are printed. See Figure 18 
on page 306. 


DUMP NOCOMPARE-——When DUMP is spect tied CNOCOMPARE is a 
default), each record is listed in the dump format. In 
addition, the name and volumes of each indirectly related 


entry are also listed. Within the “unsorted entries™ group, 


the CRA's self-describing records (Ccontrol intervals through 
8) are printed, and any free space records and records not 
yet printed are printed. See Figure 19 on page 309 


NAME COMPARE—When COMPARE is specified (NAME is a default), 
only the name of each miscompared catalog entry is listed. 

A miscompared catalog entry is one whose information is not 
identical to the information contained in the entry's copy 
in the catalog recovery area. A MISCOMPARE message is 
printed that identifies the most serious level of 
miscomparison. Within the "unsorted entries” group, 
miscompared records not yet printed out are printed. See 
Figure 20 on page 312 | 


DUMP COMPARE——When DUMP and COMPARE are specified, only the 
records (in dump format) of each miscompared catalog entry 
are listed. A miscompared catalog entry is one whose 
information is not identical to the information contained in 
the entry's copy in the catalog area. For each entry, the 
catalog recovery area copy is listed first, followed by the 
catalog entry, followed by a line that contains asterisks to 
identify each miscompared byte. Following each entry, a 
MISCOMPARE message is printed that identifies the most 
serious level of miscomparison. Within the "unsorted 
entries™ group, miscompared records not yet printed out are 


Printed in the dump format. See Figure 21 on page 3135. 


Note: As explained above, all MISCOMPARE messages result 
from a comparison between the catalog and the CRA. If the 
comparison shows that the catalog and CRA records are not 
identical, no inference is given as to which is correct. 
You must make this determination yourself by looking at 
other mismatches in the same listing and by examining 
related records in the catalog or CRA 


SEQUENTIALDUMP—When SEQUENTIALDUMP is specified, each 
record in the catalog recovery area is printed. The format 


of the output is the same as that of the DUMP NOCOMPARE, 


except that the entries are not sorted into groups or 
alphabetic sequence. 


See Catalog Diagnosis Reference for a complete description 
of catalog recovery area record formats, catalog record 
formats, and relationships between catalog records. 
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L} FOR LISTCRA JOBS 


job control language (JCL) statements that can be used to 


catalog recovery areas are: 
LISTCAT JOB rer 
STEP1 EXEC PGM=IDCAMS 
STEPCAT DD DSN=YOURCAT, DISP=SHR 
CATDD DD DSN=YOURCAT, DISP=OLD 
CRADD1 DD VOL=SER=333001,UNIT=DISK, DISP=O0OLD 
CRADD2 DD ¥&~=«OVOL=SER=333002,UNIT=DISK, DISP=O0OLD 
OUTDD DD DSN=LISTCRA. OUTPUT, UNIT=TAPE, 


VOL=SER=TAPE10,LABEL=(€1,NL),DISP=CNEW, KEEP), 
DCB=CRECFM=VBA, LRECL=125, BLKSIZE=629 ) 
SYSPRINT DD SYSOUT=A 
SYSIN DD xX 
LISTCRA - 
COMPARE - 
DUMP - 
INFILECCRADD1,CRADD2) - 
CATALOGCYOURCAT/PASSWORD CATDD) - 
MASTERPWCSECRET) —- 
OUTFILECOUTDD) 


JOB statement contains user and accounting information 
ired for your installation. 


EXEC statement identifies the program to be executed, IDCAMS 
t is, the access method services program). 


STEPCAT DD, which allocates your catalog. This is only : 
required if the COMPARE option is specified. The catalog 
must be open as a catalog before it can be opened as a data 
set through the DD statement that so identifies it for the 
comparisons. 


CATDD, which specifies the catalog to be opened as a data 
set and compared to the catalog recovery areas. This is 
only required if the COMPARE option is specified. 


CRADDI, which specifies a volume whose catalog recovery area 
CCRA) is to be listed. 


CRADD2, which specifies another volume whose CRA is to be 
listed. 


OUTDD, which specifies an alternate output file, so that the . 
LISTCRA output can be written onto an auxiliary storage 
device. The LISTCRA command's OUTFILE parameter points to 
the OUTDD DD statement. Only the LISTCRA output is written 
to the alternate output device. JCL statements, system 
messages, and job statistics are written to the SYSPRINT 
output device. 


a DSN=LISTCRA.OUTPUT specifies the name for the magnetic 
tape file. 


UNIT=TAPE and VOL=SER=TAPE10 specify that the file is to 
be contained on magnetic tape volume TAPEI1O. 


= LABEL=C1,NL) specifies that this is the first file ona 
nonlabeled tape. You can also use a standard-labeled 
tape by specifying LABEL=(1,SL). If subsequent job 
steps produce additional files of LISTCRA output on the 
same tape volume, you should increase the file number in 
each job step's LABEL subparameter (that is, 
LABEL=€2,NL) for the second job step, LABEL=(€3,NL) for 
the third job step, and so on). 


~ DISP=(NEW,KEEP) specifies that this is a new tape file 
and is to be rewound when the job finishes. If a 
subsequent job step prints the tape, DISP=CNEW,PASS) 
should be specified. If your job step contains more 
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than one LISTCRA command, DISP=CMOD,KEEP) or 
DISP=(MOD,PASS) can be used to concatenate all of the « 
LISTCRA output in one sequential file. ie 





— DCB=CRECFM=VBA,LRECL=125,BLKSIZE=629) specifies that the 
LISTCRA output records are variable length, blocked 
5-to-1, and are preceded by an ANSI print-control 
character. 


° SYSPRINT DD, which is required for each access method 
services job step. It identifies the output queue, 
SYSOUT=A, on which all LISTCRA output and system output 
messages are printed Cunless the OUTFILE parameter and its 
associated DD statement is specified; see OUTDD above). 


Note: If you want al] output to be written to an auxiliary 
storage device, replace "OUTDD' with "'SYSPRINT' in the OUTDD DD 
statement and omit the SYSPRINT DD SYSOUT=A statement. 


® SYSIN DD, which specifies, with an asterisk (X%), that the 
statements that follow are the input data statements. A 
'/¥" terminates the input data statements. 





The LISTCRA command parameters shown above are common to the 
LISTCRA DUMP COMPARE example that follows. Other LISTCRA 
parameters may be coded and the output that results is 
illustrated. 


COMPARE, which specifies that the CRA entries are to be compared 
with the catalog entries identified by the CATALOG parameter. 
Only those that miscompare will be listed. 


DUMP, which specifies that each listed entry is to be printed in 
its entirety in both hexadecimal and character form. 


INFILE, which specifies the two DD statements, CRADDI] and a 

CRADD2, which identify the two volumes whose CRAs are to be ! 
Taal ae with the catalog aneeses and the miscomparing entries Se 
iste 


CATALOG, which identifies the DD statement, CATDD, which 
identifies the catalog, YOURCAT, whose entries are to be 
compared with those in the CRAs. If the catalog is password 
protected, its master password, PASSWORD, is required. 


MASTERPW, which specifies the master password of the master 3 
catalog, SECRET, to enable the CRAs to be OPENed. 


OUTFILE, which points to the OUTDD DD statement. The OUTDD DD 
sorb oade allocates an alternate output file for the LISTCRA 
output. 


If you want to print the LISTCRA output that is contained on an 
alternate output file, you can use the IJEBGENER program. The 
following shows the JCL required to print the alternate output 
file, LISTCRA.OUTPUT, that was allocated previously: 


//PRINTOUT JOB 


//STEPL EXEC PGM=IEBGENER 

//SYSUTI DD DSN=LISTCRA. OUTPUT, UNIT=TAPE, 
DCB=CRECFM=VBA, LRECL=125, BLKSIZE=629) 

//SYSUT2 DD SYSOUT=A 

“/SYSPRINT DD SYSOUT=A 

//SYSIN DD DUMMY 

7% 

4/ 
































LISTCRA OUTPUT LISTING 


When you specify LISTCRA with no parameters, each entryname, its 
volume(s), and the name and volume(s) of each related entry are 

listed. The same listing would result if the NAME and NOCOMPARE 
parameters were specified. 





You can use this type of listing to list the name of each 
catalog entry whose copy is in the catalog recovery area, and to 
determine the number of entries in each catalog recovery area. 
The total number of entries is an approximate size, in records, 
of the catalog recovery area. 
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LISTING OF CATALOG RECOVERY AREA FOR VOLUME -- 333301 ~~ VSAM ENTRIES | 


VOL - 333301 
CRAVOLRCD - 10707774 23:35:00 
FGDSCBVSAM - 10707774 23:35:00 
FGDSCBDUMP ~ 10/07/74 23:35:00 


CLUS - AA.LISTCRA.ESDS 


DATA - TFGICIAN. VSAMDSET. 
DATA VOL 
333301 


AIX -—- AA2.LR.ESDS 
DATA VOL - 
333301 
INDX VOL - 
333301 


AIX -~ AAI.LR.ESDS 
DATA VOL - 
333301 
INDX VOL - 
333301 


PATH - AAU.LR.ESDS 
UPGD - 

CLUS ~ AA.LISTCRA.KSDS 
DATA - T3C55DD0. VSAMDSET. 


DATA VOL 
333301 


INDX - pare renee 


INDX V 
333301 


AIX - AA1.LR.ESDS 
DATA - TCD41020. VSAMDSET. 
DATA VO 
533301 
INDX - TCDG1FO0.VSAMDSET. 
INDX VOL 
333301 
CLUS - AA.LISTCRA.ESDS 
PATH - AALU.LR.ESDS | 
PATH - AAIN.LR.ESDS 
CLUS - LR.MCKEYRNG.KSDS 


DATA - TF081480. VSAMDSET. 
DATA VOL ~- HIGH KEY 


\ 


DFD74280.T&861DAD4.TF41C9AD0 


DFD74280 


DFD74280 


DFD74280. 


DFD74280 


DFD74280 


333301 - CICICICICICICICIC5F9 
333301 - CICICICICICICICLESES 


INDX - TFO082370.VSAMDSET. 


INDX VOL - 
333301 
333301 


DFD74280 


-T861DB0A 


- T861DB0A 


T861DB23 


~-T861DB23 


.T861DBO0E. 


-T861DB0E 


» T5C55DD0 


. T5C56E70 


»1CD41020 


. TCDG1F00 


TF081480 


. TF082370 





Figure 18 (Part 1 of 2). Example of LISTCRA NAME NOCOMPARE Output 


\i j 
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LISTING OF CATALOG RECOVERY AREA FOR VOLUME -- 333301 -- OTHER ENTRIES 


UCAT - USERCAT2 


DATA VOL - 
333304 
NUMBER OF ENTRIES PROCESSED 
CLUS - 3 
DATA - 4 
AIX - 1 
INDX - 2 
PATH - 3 
VOL - 1 
UPGD - 1 
SUM - 15 


Figure 18 (Part 2 of 2). 


LISTCRA NAME NOCOMPARE Output Notes: 





Example of LISTCRA NAME NOCOMPARE Output 





The title line of the output contains the volume serial 
number and identifies the group that the following entries 
are within Cin this case, VSAM Entries). 


The time stamps: 


CRAVOLRCD is the timestamp of the CRA volume record. It is 
updated only when the first catalog record and first CRA 
volume record are updated, after the CRA is opened when VSAM 
is running. (Note: If the volume is moved to a DOS/VS 
system and used there, the CRAVOLRCD timestamp is updated 
each time the catalog and CRA volume records are updated for 
a space allocation change). 


FG4DSCBVSAM is a timestamp in the format-4 DSCB, and is 
updated in the same manner as the CRAVOLRCD timestamp. 


FGDSCBDUMP is also a timestamp in the format-4 DSCB, and is 
updated in the same manner as the CRAVOLRCD timestamp. It 
1s also updated whenever the operating system utility 
program IEHDASDR dumps the volume. 





VSAM entries are listed along with the entryname and 
volume(s) of each related entry. 


Paths are shown as related only to the entry to which the 
path provides access. A path that serves as an alias for a 
VSAM data set is listed with the data-set's entry. A path 
that shows the relationship of an alternate index to a base 
cluster is listed with the alternate-index's entry only. 


UPGD indicates that there are alternate indexes in the 
base-cluster's upgrade set. If you want to identify the 
indexes in the upgrade set, use the DUMP NOCOMPARE option. 
The high-key value of each keyrange is shown. 


SUM is the total number of catalog recovery area entries 
printed. 
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LISTCRA DUMP OUTPUT LISTING 


When you specify LISTCRA with the DUMP parameter, each record in 
the catalog recovery area is listed in dump format. In 
addition, the name and volumes of each indirectly related entry 
are also listed. The same listing would result if the DUMP and 
NOCOMPARE parameters were specified. 


When you specify LISTCRA SEQUENTIALDUMP, the same listing 
results, except that the records are listed in their entry 
sequence within the catalog recovery area. 


You can use this type of listing to list the complete contents 
of each catalog entry whose copy is in the catalog recovery 
area, and to determine the exact number of entries and records 
in each catalog recovery area. 








fo ~ 
Bi \ 
s . 
























eo. - 333301 


£00003} o§0000C) 
.0020 00000000 
0040 00000000 
0060 1152A820 
0080 00000000 
OOAO 86000100 
00CO 05000037 
00EO 00378800 
0100 88001000 
0120 1500003E 
0140 003E8800 
0160 08002000 
0180 46000C00 
O1A0 B23F0000 


(CLUS - KSDS0O1 


00000017 
00000000 
40404040 
FFFFFFFF 
0200000C 
001A0006 





DATA 


00000D 
0020 
0040 
0060 
0080 
OOAO 
ooco 
OOEO 
0100 
0120 
0140 
0160 


INDX 


OOOOOF 
0020 
0040 
0060 
0080 
OOAO 
00CcO0 
OOEO 
0100 
0120 
0140 


PATH 


000010 
0020 
0040 
0060 
0080 


000000 18 
00000000 
CSE34BC4 
FFFFFFFF 
OOOOOOD0F 
00620201 
00000 300 
00000000 
00000000 
O9F 3F 3F 3 
00010000 
00150000 


00000019 
00000000 
CSE34BC4 
FFFFFFFF 
OOFFFFFF 
00620201 
00000000 
00000000 
00002800 
FOF 10000 
00001400 


- PATHO! 


QOOOOOTA 
00000000 
40404040 
FFFFFFFF 
0200000C 


OVF 3F 3F 3 
QOQO000000 
00000000 
00 305020 
260000 3E 
00378800 
88000600 
0B0000 37 
00378800 
88001600 
1B000000 
00 3C0800 
0054861D 
4C000C00 


OF 3F 3F 3 
00000000 
40404040 
FF74280F 
020 30000 
C70000 1B 


OIF 3F3F3 
00000000 
COC4FTF4 
FF74280F 
FIOOOOFF 
O0000A902 
00000000 
00000000 
000000 30 
F3FOF100 
00000014 
00000000 


OF 3F3F3 
00000000 
COC4F7F4 
FF74280F 
FFOOOOFF 
00006803 
00000200 
00000000 
00000000 
80010000 
01000200 


OIF3F3F3 
00000000 
40404040 
FF74280F 
02030006 


F3FOF10U 
00000000 
00000000 
090000 32 
00000000 
010000 37 
00480800 
88000C00 
110000 37 
00 3E8800 
0800 1C00 
21000C00 
B2050000 
0058861D 


F3FOFT00 
00000000 
40404040 
QOO000FO0O 
12020400 
00000000 


F 3FOF 100 
00000000 
F2F8FO4B 
00000000 
FFFFFFFF 
02000068 
00000010 
00000000 
00000000 
00800 100 
00010002 
00000000 


F3FOF100 
00000000 
F2F8FO4B 
00000000 
FFFFFFFF 
01000000 
00000 1F9 
00000001 
00000000 
00000000 
01000200 


F3FOF100 
00000000 
40404040 
O0O000F80 
Cc 3000017 


Figure 19 (Part 1 of 2). 


V009 3050 

1BDO00 
00000000 
E6019B00 
000D8500 
88000200 
070000 37 
00378800 
88001200 
170000 3E 
000C 0800 
0051861D 
47000C00 
B2 3FO0O00 


OOOE 3050 
C 300A800 
40404040 
00000000 
00004401 
00000000 


000D 3050 
C4016200 
E3F8F6F 1 
20000000 
FFFFFFOO 
03010000 
OOOOOO00F 
00000000 
00000000 
00000000 
00000002 
00000000 


OOOF 3050 
c9015700 
E3F8F6F 1 
2000F FFF 
FFFFFFOO 
44010062 
00000000 
00000000 
00000000 
00000000 
01000100 


00100000 
D9009800 
40404040 
00000000 
0006C 400 





7 
00000000 


' 133 36DBF 


0100000E 
00 378800 
88000800 
ODO000 37 
00378800 
88001800 
1p000018 
B1D60000 
0055861D 
50000C00 


200986 


Pe 3F3F3 F3FOF100 


00000000 
BF 380002 
85000200 
030000 37 
00 378800 
88000E00 
1300003E 
00 3E8800 
0800 1E00 
42000C00 
B2050000 
006086 1D 


BA4SEOO0U 


LISTING OF CATALOG RECOVERY AREA FOR VOLUME - - 


VOOd0GO000 
QOOOO00V0 
00c0000u0 
00000500 
OOOF8500 
88000400 
090000 37 
00378800 
88001400 
190000 3E 
00240800 
0052861D 
48000C00 
B79CO006 


QOOO0000 


6GD2Z2E2C4 E2FOF 140} 40404040 


40404040 
00070000 
0006C 400 
00000000 


2009861D 
SFE3F1F8 
C4F9FICS 
22000000 
00000000 
00440100 
F9000000 
01000000 
00000000 
00000000 
00000001 
00000000 


2009861D 
SFE3F1F8 
C4F9F9C5 
FFFFOOOO 
00000000 
60000060 
00000000 
00000000 
0006C 300 
28000000 
00000000 


000086 1D 
6CD7C1E3 
40404040 
00000000 
00180006 


40404040 
00C00000 
00180006 
00000000 


- T188D0C0. VSAMDSET . DFD74280 .T861D99E .T188D0C0 


8A4E861D 
F8C4FOC 3 
4SBE3F1F8 
01000001 
06000000 
62608000 
00000000 
00000000 
000006C 3 
00300000 
00000000 
00000000 


- T188E190.VSAMDSET .DFD74280.T86 1D99E.T188E190 


8A4E861D 
F8CSFIF9 
4BE3F 1F8 
01000001 
05000000 
00010003 
00000000 
00000000 
00170327 
02000014 
0027FF00 


8A4E0000 
C8FOF 140 
40404040 
00c00000 
c9000019 


40404040 
00000201 
¢c9000019 
00000000 


99E20000 
FO4BESE2 
F8C4FOC 3 
80000000 
C0000000 
60000000 
00000000 
00000000 
00001703 
00100000 
OOOO2FFF 
00000000 


99E20000 
FO4BESE2 
F8CSFIF9 
80000000 
c0000000 
00140000 
00000000 
00000000 
30502009 
00140000 
00000000 


00000000 
40404040 
40404040 
00000201 
00000000 


333301 


00000000 
Q0000000 
0086 1 DEE 
(X0000000 
0 30000 37 
00378800 
88000A00 
QFOO00 37 
00 3E8800 
8800 1A00 
¥FO000 30 
B1D60000 
0057861D 
2C 1DB173 


QVO00O000 
40404040 
4SOFFFFFF 
ON0006024 
O0006D900 
QOOO0000 


00000000 
CID4C4E2 
FOFFFFFF 
000000 30 
00010100 
03001400 
00000000 
00000000 
27305020 
03000140 
O0O06E800 
00000000 


00000000 
C ID4C4E2 
FOFFFFFF 
00000028 
00010100 
00140000 
00000000 
00000000 
F3F3F3F3 
02000000 
00000000 


00000000 
40404040 
4OFFFFFF 
00000602 
00000000 





-- VSAM ENTRIES 


ee om 
LVL... 


S33IOV Losses 


eoocoseeeeeeevreevre eevee ee eee eee Bee ee ee 


eeceseeseeeeer eee 


enn eevvreereeovre ees ee rere ee ee ee ewe eee 


Pe ee ee ed 


Pe ee ee ee Se 2 


ee) 


re 


Pe ee ed 


ee} 


) 


re 


eooereer ere eee ewe ee ee ee ee 


ee) 


ee 


oeceoererewreoere eer eee e eee eee ee eer eee eee 


coco oe eee ere eee weer eee ee ee ee eee eae eee 


oeoeeeweo ewe eee eee ewe wae eee eee wee eevee 


eeoeseeeneeeee ee ewe eee ee ee ew eewe eee 


ee ee 


Example of LISTCRA DUMP NOCOMPARE Output 
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AIX 


- AIXx01 


DATA VOL - 


eo 333301 


INDX VOL - 


UPGD 


000014 
0020 
0040 


DATA 


000038 
0020 
0040 
0060 
0080 
OOAO 
00co 
OOEO 
0100 
0120 
0140 
0160 
0180 
01A0 
01c0 


INDX 


00003A 
0020 
0040 
0060 
0080 
GOAO 
00cOo 
OOEO 
0100 
0120 
0140 
0160 
0180 


Figure 19 (Part 2 of 2). 


333301 





0000001 OIF3F3FY F3FOF100 00143050 2000861D 8A4E0000 
00000008 00000000 E8004B00 
01000AC4[ 0000 1GC9f 00001ND0 00000000 00000000 00000000 


000000 


- TFO81480.VSAMDSET .DFD74280 .T861DBOE.TFO081480 


00000048 
00000000 
CSE34BC4 
FFFFFFFF 
00000000 
00620201 
00001400 
00000000 
00000000 
OOF 3F3F3 
0018000A 
00040003 
00000000 
C1cé6Cc 100 
OO00004F 


- TFO82370.VSAMDSET .DFD74280.T861DBOE. TF082370 


00000049 
00000000 
CSE34BC4 
FFFFFFFF 
OOFFFFFF 
00620201 
00001400 
00000000 
00000000 
O9F 3F3F3 
00190000 
2009F 3F3 
40001900 


OIF3F3F3 
00000000 
C6C4F7F4 
FF74280F 
SOOOOOFF 
00006803 
00000000 
00000000 
00000050 
F3FOF100 
c1c1c1c1 
00040001 
00002800 
OACIC1C1 
FFO00000 


OIF3F3F3 
00000000 
C6C4F7F4 
FF74280F 
FFOOOOFF 
00006803 
00000000 
00000000 
00000028 
F3FOF100 
00000014 
F3F3FOF1 
00000000 


F3FOF100 
00000000 
F2F8FO4B 
00000000 
FFFFFFFF 
0 10000BD 
00000002 


00000000. 


00000000 
00800100 
cicicicl 
00000000 
00005000 
cicicicl 
00000000 


F3FOF100 
00000000 
F2F8F04B 
00000000 
FFFFFFFF 
010000A9 
00000002 
00000000 
00000000 
00800100 
00010003 
00004000 
00000000 


00383050 
C401C500 
E3F8F6F 1 
20000000 
FFFFFFOO 
03020000 
00000000 
00000000 
00000000 
00000000 
C1C1000A 
000027FF 
00000200 
C1E9E900 
00000000 


003A3050 
c9018900 
E3F8F6F 1 
2000FFFF 
FFFFFFOO 
03020000 
00000001 
00000000 
00000000 
00000000 
00060003 
00000000 
00000000 


31000000 


2009861D 
8FE3C6FO 
C4C2F0C5 
06000000 
00000000 
00440100 
50000000 
02000000 
00000000 
00000000 
cicicicl 
03273050 
00140009 
14000100 
00000000 


2009861D 
8FE3C6FO 
C4C2F0C5 
FFFFOOOO 
00000000 
00440100 
F9000000 
01000000 
00000000 
00000000 
00060001 
00000000 
00000000 


Example 


00000200 


8A4E861D 
F8FIF4F8 
4BE3C6FO 
01000001 
06000000 
62608400 
00000000 
00000900 
000006C 3 
00280000 
c1icicic1 
2009F 3F 3 
40001800 
03000500 
00000000 


8A4E861D 
F8F2F 3F7 
4BE3C6FO 
01000001 
06000000 
62600400 
00000000 
00000000 
000006C 3 
00280000 
00000000 
00000000 
00000000 


00000000 
0000C000 
00000000 


BOFOOOOO 
FO4BESE2 
F8F1F4F8 
80000000 
coo00000 
60000000 
00000000 
00000000 
00004703 
00020000 
CSF90014 
F3F3FO0F1 
OAC1C1C1 
03000500 
00000000 


BOFOOO0O0O0 
FO4BESE2 
F8F2F3F7 
80000000 
co000000 
60000400 
00000000 
00000000 
00004703 
00020000 
000027FF 
00000200 
00000000 


00000000 
00000002 


00000000 
C1ID4SC4E2 
FOFFFFFF 
00000050 


(00010100 


QAODOOA00 
00000000 
00000000 
27305020 
14000140 
00010003 
00008001 
cicicicy 
01000028 
00000000 


00000000 
CID4C4E2 
FOFFFFFF 
00000028 
00010100 
QANDOQA00 
00000000 
00000000 
27305020 
14000140 
03273050 
00140001 
00000000 


ee ee oe D.E..TFO81480.VSAMDS 
ET .DFD74280.T861DBOE.TF081480. 


CY 


ey 





oe ee eee eer eee ee ease ewoer eer wen eee 


Ses SITIO Ue sh ew oe eh hig ONG cy 
aie vale awe: ercnelaNen I....TFO82370.VSAMDS 
ET .DFD74280.T861DBOE.TFO82370... 


| 
Cr | 
oe ee se eee 


oeoe eves ewer eee er eee ewe ee 


CY 


oo eee were eee ewe wee ow eee 


Cr 


of LISTCRA DUMP NOCOMPARE Output 


LISTCRA DUMP NOCOMPARE Output Notes: 


Note: 


listed. 
or according to alphanumeric~sequence of the entryname field. 


See also Note 7, 


1. 
2. 


The 3-byte CRA control interval number, 


The 3-byte control interval number of the catalog record for 
which this iS a copy, 


The entrytype at offset X'"2C' 


below. 


When you specify SEQUENTIALDUMP, 
The entries are not sorted according to type of entry, 


in hexadecimal form. 


Cdecimal 449), 


identifies the type of catalog entry being listed. 


A 44-byte field at offset X'3l' 


the entry's entryname Cpadded with binary zeros), 
&-byte field followed by 36 bytes of binary zeros that 
contain the volume entry's volume serial number. 


The volume serial number of the recovery volume. 


A 2-byte displacement value. 
the last line containing data is listed, 


catalog records are 512 bytes long. 


As in the NAME NOCOMPARE output, 
and the fact that there is an upgrade set is given, 
with the volume serial numbers of the alternate index's data 
and index components. 


specified, the information described with this note is not 


listed.) 


(Note: 


If SEQUENTIALDUMP is 
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the same information is 


in hexadecimal form. 


a character that 


(decimal 49) that contains 
or an 


Printing is suppressed after 
even though all 


the alternate index name 


along 

















10. 











The first byte identifies the alternate index's data 
component and the next three bytes contain its catalog 
control interval number. 


The first byte identifies the alternate index's index 
component and the next three bytes contain its catalog 
control interval number. 


Because there are two key ranges for this cluster, there are 


two volume information sets of fields in the cluster's data 
and index component entries. 
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LISTCRA COMPARE OUTPUT LISTING 


When you specify LISTCRA with the COMPARE parameter, each record 
in the catalog recovery area is compared with its original in 
, the catalog. The name of each catalog entry that miscompares is 
| - listed. A miscompared catalog entry is one whose information is 
| not identical to the information contained in the entry's copy 
| in the catalog recovery area. The same listing would result if 
the NAME and COMPARE parameters were specified. 


You can use this type of listing to determine the number of 
damaged entries in your catalog, and you can get an idea of the 
type of damage that occurred to each entry. You can issue the 
EXPORTRA and IMPORTRA commands to recover the catalog and make 
its damaged entries usable. 


| LISTING OF CATALOG RECOVERY AREA FOR VOLUME -- 33353501 -- VSAM ENTRIES 


CATVOLRCD - 09/17742 23:53:47 
CRAVOLRCD - 10707774 23:35:00 
FGDSCBVSAM ~ 10707774 23:35:00 
FG4DSCBDUMP - 10/07/74 23:35:00 


CLUS - LR.DELETED.ESDS 
% MISCOMPARES - CATALOG ENTRY HAS DIFFERENT NAME 
CLUS - LR.MCHURBA.ESDS 
DATA - T73FEDAO.VSAMDSET . DFD74280.T861DAE1.T735FEDAO 
DATA VOL - 
333301 | 
% MISCOMPARES - HIGH USED RBA 
CLUS - LR.MCKEYRNG.KSDS 
DATA ~ TF081480.VSAMDSET . DFD74280.T861DBOE. TF081480 
DATA VOL - HIGH KEY 
333301 - CICICICICICIC1C1C5F9 
333301 - CICICICICICICIC1E9E9 
% MISCOMPARES - HIGH USED RBA 
INDX - TF082370.VSAMDSET . DFD74280.T861DBOE. TF082370 
INDX VOL - 
333301 
333301 
% MISCOMPARES - STATISTICS 


NUMBER OF ENTRIES PROCESSED 


CLUS - 235 
DATA - 18 
AIX - 8 
INDX - ll 
PATH ~- 5 
VOL - 1 
UPGD - 3 
SUM - 69 


IDC0665I NUMBER OF ENTRIES THAT MISCOMPARED IN THIS CRA —- 3 
IDCO0877I NUMBER OF RECORDS THAT MISCOMPARED IN THIS CRA - 4 


Figure 20. Example of LISTCRA NAME COMPARE Output 


312 MVS/XA VSAM Catalog: Access Method Services Reference 





a 
Q 





LISTCRA NAME COMPARE Output Notes: 


In addition to the timestamps described for the NAME 
NOCOMPARE output Cnoted previously), 
catalog volume record, CATVOLRCD, 





the timestamp in the 


is listed. CATVOLRCD is 


updated in the same manner as the CRAVOLRCD timestamp. 


e The MISCOMPARES message always refers to the record listed 


above it. 


d 


See "Regaining Access to Data™ in the Catalog 


for the cause and seriousness of this 


MISCOMPARES message. 


e The number of records is sometimes larger than the number of 


entries, 


because an entry might consist of a catalog record 


and one or more extension records that failed to compare 


correctly. 


LISTCRA DUMP COMPARE OUTPUT LISTING 


When you specify LISTCRA with the DUMP and COMPARE parameters, 
each record in the catalog recovery area is compared to its 


original in the catalog. 
catalog recovery area that miscompares is listed, 
its original catalog entry (which is damaged), 


Each catalog entry's copy in the 


followed by 
followed by 


asterisks to indicate each miscompared byte. 


You can use this type of listing to determine the exact damage 


that occurred to each entry. 
or all of the damage by using the ALTER command. 


You might be able to correct some 


You can issue 


the EXPORTRA and IMPORTRA commands to recover the catalog and 
make its damaged entries usable. 





CLUS - 


@—+ 000020 


CATRCD 
0020 


0040 
0060 


0080 


DATA 


000021 
CATRCD 


0020 


0040 


0060 


ri 
0080 


OOAO 


LR .MCHURBA . ESDS 


000000 2c 
000000 2c 


00000000 
00000000 


40404040 
40404040 


FFFFFFFF 
FFFFFFFF 


002D0000 
002D0000 


- T73FEDAO.VSAMDSET . DFD74280.T861DAE1 .T7 3FEDAO 


0000002D 
0000002D 


00000000 
00000000 


CSE34BC4 
CSE34BC4 


FFFFFFFF 
FFFFFFFF 
00000000 
00000000 


00620201 
00620201 


® MISCOMPARES - 


Figure 2l. 


OF 3F3F3 
OF 3F3F 3 


00000000 
00000000 


40404040 
40404040 


FF74280F 
FF74280F 


00000000 
00000000 


OIF3F3F3 
OIF 3F3F3 


00000000 
00000000 


C6C4F7F4 
C6C4F7F4 


FF74280F 
FF74280F 
SOOOOOFF 
SOOOOOFF 


00006803 
00006803 


F 3FOF100 
F 3FOF 100 


00000000 
00000000 


40404040 
40404040 


OOOOOFO0 
OOOO0OFO0O 


00000000 
00000000 


F 3FOF 100 
F3FOF100 


00000000 
00000000 


F2F8F04B 
F2F8FO4B 


00000000 
00000000 
FFFFFFFF 
FFFFFFFF 


01000000 
01000000 


00203050 
00203050 


C 3008200 
C 3008200 


40404040 
40404040 


00000000 
00000000 


00000000 
00000000 


00213050 
00213050 


c4015700 
Cc4015700 


E3F8F6F 1 
E3F8F6F1 


20000000 
20800000 
ee 
FFFFFFOO 
FFFFFFOO 


44010062 
44010062 


HIGH USED RBA -—@ 


2009861D 
2009861D 


6CD3D94B 
6CD3ID94B 


40404040 
40404040 


00000000 
00000000 


00000000 
00000000 


2009861D 
2009861D 


SFE4SF7F3 
SFE4F7F 3 


C4C1C5F1 
C4C1C5SF1 


04000000 
04000000 
00000000 
00000000 


60000060 
60000060 


8A4E0000 
8A4E0000 


D4C 3C8E4 
D4C 3C8E4 


40404046 
40404040 


00020100 
00020100 


00000000 
0000000U 


8A4E861D 
SA4E86 1D 


c6csc4c 1 
c6csc4c 1 


4BE3F7F 3 
4BE3F7F 3 


01000001 
01000001 
05000000 
05000000 


00000000 
00000000 


LISTING OF CATALOG RECOVERY AREA FOR VOLUME -- 


OOOOOO00 
OODOOOO00 


DIC 20 14B 
DIC 20 14B 


40404040 
40404040 


OV004401 
O0004401 


OODOD0000 
OOOOOO0O 


AE2E0000 
AE2EV000 


FO4BESE2 
FOSBESE2 


céecsc4c t 
cé6écsc4c 1 


80000000 
80000006 

es 
00000000 
CO0000000 


00000000 
00000000 


333301 -- VSAM ENTRIES 


VQOOOOO00 
OOOOOO00 


CSE2C4E2 
COEQZC4E2 
4OFFFFFF 
4OFFFFFF 


ONV06C 400 
OO06C 409 


QO0000000 
OO0000000 


VOO000000 
00000000 


CID4SC4E2 
CID4C4E2 


FOFFFFFF 
FOFFFFFF 


00000028 
00000028 
00010100 
00010100 


00140000 
00140000 


Example of LISTCRA DUMP COMPARE Output 


SS SION os ae as ioe akan ive fest 


ec eet core le Caudharnese -Q 


oe eee 


ee eee 


ed 


Ce ee? 


Biase (8, Sperone yataseuen D....T73FEDAO.VSAMDS 
siahere6 Seed Wie D....T73FEDAO.VSAMDS 


ET .DFD74280.T861DAE1.T73FEDAO... 
ET .DFD74280.T861DAE1.T73FEDAO... 


ee ey 


er er ? 
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LISTCRA DUMP COMPARE Output Notes: 


l. 
2. 


The 3-byte CRA control interval number in hexadecimal form. 


Each pair of hexadecimal-data lines is the information in 
the catalog recovery area's copy of the catalog record, 
followed by the information in the catalog record, for the 
same displacement. 


Asterisks are printed below the bytes in which a miscompare 
exists and, in the left margin, the miscompared lines are 
flagged with a single asterisk. 


See "Regaining Access to Data™ in the d 
for the cause and seriousness of this MISCOMPARES 
message. 
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Figure 22 shows the format of output from the CHKLIST command. 


For each checkpoint entry listed under "CHECKID", the other 
columns give dsname, ddname, unit, and volume information for 
each tape data set that was open at the time of the checkpoint. 
Asterisks under "UNIT™ indicate an unrecognizable unit type. 
"VOLUME X OF Y IS CURRENT™ indicates the volume sequence number 
of the volume mounted at the time of the checkpoint and the 
total number of volumes in the data set. each volume's volume 
serial number is listed, and an asterisk indicates the volume 
mounted at the time of the checkpoint. 





CHKLIST INFILE(CHKPT) CHECKID(C0000001 C0000002) 


IDCAMS SYSTEM SERVICES TIME: 21:34:43 01/16/75 

OPEN TAPE DATA SET LIST FROM CHECKPOINT DATA SET - CHKPT DATASET 

CHECKID DSNAME DDNAME UNIT VOLUMES ~ * INDICATES CURRENT VOLUME 
co0000001 


USER.TAPE.DATASETO DDN2VS11 2400-7TRK VOLUME 1 OF 1 IS CURRENT 
120001® 


USER . TAPE .DATASET 1 DDN3VS11 2400-9TRK VOLUME. 3 OF 4 IS CURRENT 
130001 130002 130003* 130004 


USER . TAPE . DATASET2 DDONSVS11 3400-7TRK VOLUME 1 OF 1 IS CURRENT 
140001 


c0000002 


USER .TAPE.DATASET3 DDNAME32 2400-9TRK VOLUME 8 OF 8 IS CURRENT 
230001 230002 230003 230004 230005 
230006 230007 230008* 


USER.TAPE.DATASETS DDNAME42 2400-9TRK VOLUME 20 OF 24 IS CURRENT 
240001 240002 240003 240004 240005 
240006 240007 240008 240009 240010 
240011 240012 240013 240014 240015 
240016 240017 240018 240019 2480020¢ 
240021 240022 240023 240024 


IDCOOO1I FUNCTION COMPLETED, HIGHEST CONDITION CODE WAS 0 
IDCOOO2I IDCAMS PROCESSING COMPLETE. MAXIMUM CONDITION CODE WAS 0 


Figure 22. Example of CHKLIST Output 
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Parameter 
AFF | 


CHKPT 


DATA 


DCB 


DISP 


Figure 23 








You should be aware that some specifications do nothing in a 
VSAM environment or might cause problems for you. Figure 23 
shows the DD statement parameters and subparameters to be 
avoided with VSAM. For more information, see JCL 


Subparameter 


ddname 


EOV 


All 


CATLG 


DELETE 


MoD 


KEEP 


NEW 


(Part 1 of 3). JCL 


Comment 


You must use this parameter carefully. If 
the cluster components (the data and its 
index) reside on unlike devices, the results 
of an AFF specification are unpredictable. 


Because checkpoints at end of volume are 
executed only for BSAM and QSAM data sets, 
this parameter does not apply to VSAM data 
sets and need not be coded. 


Because there is no way to get VSAM data into 
the input stream, this parameter is not 
applicable to VSAM. 


The access method control block CACB), not 
the DCB, describes VSAM data sets; therefore, 
the DCB parameter is not applicable to VSAM. 
An access method control block is generated 
by an ACB or GENCB macro, and can be modified 
by a MODCB macro. 


CATLGVSAM data sets are cataloged and 
uncataloged as a result of an access method | 
services command; if CATLG is coded, a message 
is issued, but the data set is not cataloged. 


VSAM data sets are deleted as a result of an 
access method services command; if DELETE is 
coded, a message is issued, but the data set 
is not deleted. 


For VSAM data sets, MOD is treated as if OLD 
were specified, except for processing with an 
ISAM program, in which case MOD indicates 
resume load. 


Because KEEP is implied for VSAM data sets, 
it need not be coded. 


VSAM data sets are initially allocated as 

a result of the access method services 

DEFINE command. If NEW is specified, space 
is allocated and it is never used 

by VSAM. Moreover, an access method services 
request for space may fail if the DISP=NEW 
acquisition of space causes too little space 
to remain available. 


DD Parameters 
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( Parameter Subparameter 
- UNCATLG 


DSNAME dsnameCareaname) 


dsname( generation) 


dsname(member ) 


All temporary 
dsnames 


All backward 
DD references 


of the form 
X.ddname 

LABEL BLP, NL, NSL 

IN 

( OUT 

LABEL NOPWREAD 
PASSWORD 

SL» SUL 

SEP ddname 

SPACE 





Comment 


VSAM data sets are cataloged and uncataloged 
as a result of access method services commands; 
if UNCATLG is coded, a message is issued, but 
the data set is not uncataloged. 


The name 18S used; areaname is ignored. 


A generation data group entry must exist in 
the catalog for this to apply. 


The name is used; member is ignored. 


Because VSAM data sets are built by access 
method services, which uses the data set 
name supplied in the DEFINE command; 
temporary names cannot be used with VSAM. 


If the object referred to is a cluster and 
the data set and index reside on unlike 
devices, the results of a backward DD 
reference are unpredictable. 


Because these subparameters have no meaning 
for direct access devices, they do not apply 
for VSAM data sets, which all reside on 
direct access storage. 


Because IN is used to override DCB 
subparameters and the DCB parameter does not 
apply to VSAM data sets, IN does not apply. 


Because OUT is used to override DCB 
subparameters and the DCB parameter does not 
apply to VSAM data sets, OUT does not apply. 


The password protection bit is set for all 
VSAM data sets, regardless of the 
PASSWORD/NOPWREAD specification in the LABEL 
parameter. 


Although these parameters apply to 

direct access storage devices, SL is always 
used for VSAM, whether you specify SL, SUL, 
or neither. 


You must use this parameter carefully. If 
the cluster components, the data and its 
index, reside on unlike devices, the results 
of a SEP specification are unpredictable. 


VSAM data sets are initially allocated as a 
result of the access method services DEFINE 
command. Therefore, if SPACE is specified 

on the DD statement, an extent is allocated 

that is never used by VSAM. Moreover, an access 
method services request for space may fail 

as a result of the SPACE acquisition of space. 


Figure 23 (Part 2 of 3). JCt DD Parameters 
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Parameter Subparameter | Comment 





SYSOUT If SYSOUT is coded with a mutually exclusive 
parameter (for example, DISP), the job step 
is terminated with an error message. 


UCS All | Because this parameter applies only to 
unit record devices, it does not apply to VSAM. 


UNIT AFF You must use this subparameter carefully. 
If the cluster components, the data, and its 
index reside on unlike devices, the results 
of UNIT=AFF are unpredictable. 


UNIT SEP You must use this subparameter carefully. 
If the cluster components, the data, and its 
index reside on unlike devices, the results 
of UNIT=SEP are unpredictable. 


VOLUME REF You must use this subparameter carefully. 
If the referenced volumes are not a subset 
of those contained in the catalog record 
for the data set, the results are 


unpredictable. 
volseq# Results are unpredictable. 
volcount This subparameter is used to request some 


number of nonspecific volumes. Because all 
VSAM volumes must be specifically defined 
before processing, volcount is not applicable 
to VSAM data sets. 


Figure 23 (Part 3 of 3). JCL DD Parameters 


oe ; 
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Access method services can be invoked by a problem program 
through the ATTACH, LINK, or LOAD and CALL macro instructions. 


The dynamic invocation of access method services enables 
respecification of selected processor defaults as well as the 


ieee to manage input/output operations for selected data 
sets. 


AUTHORIZED PROGRAM FACILITY (CAPF) 
For information on APF authorization, see Catalog Administration 
Guide or VSAM Administration Guide. 

INVOKING MACRO INSTRUCTIONS 
The following descriptions of the invoking macro instructions 
are related to Figure 24 on page 322, which describes the 
argument lists referenced by the invoking macros. 


LINK OR ATTACH MACRO INSTRUCTION 


Access method services may be invoked through either the LINK or 
the ATTACH macro instruction. 


The format of the LINK or ATTACH macro instruction is: 


LINK{ ATTACH 





EP=IDCAMS 
specifies that the program to be invoked is IDCAMS. 


PARAM= 
specifies the addresses of the parameters to be passed to 
IDCAMS. These values can be coded: 


d 

specifies the address of an option list, which can be 
specified in the PARM parameter of the EXEC statement 
and is a valid set of parameters for the access method 
services PARM command. If you do not want to specify 
any options, this address must point to a halfword of 
binary zeros. Figure 24 on page 322 shows the format 
of the options list. 


specifies the address of a list of alternate dd names 
for standard data sets used during IDCAMS processing. 
If standard ddnames are used and this is not the last 
parameter in the list, it should point to a halfword 
of binary zeros. If it is the last parameter, it may 
be omitted. Figure 24 shows the format of the 
alternate ddname list. 


specifies the address of a 3- to 6-byte area that 
contains an EBCDIC starting page number for the system 
cutput file. If the page number is not specified, but 
this is not the last parameter in the list, the 
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parameter must point to a halfword of binary zeros. 

If it is the last parameter, it may be omitted. If 

omitted, the default page number is 1. Figure 24 on 
page 322 shows the format of the page number area. 


specifies the address of a list of externally 
controlled data sets and the addresses of 
corresponding 1/0 routines. If no external I/0 
routines are supplied, this parameter may be omitted. 
Figure 24 shows the format of the I/0 list. 


causes the high-order bit of the last address 
parameter of the PARAM list to be set to l. 


LOAD AND CALL MACRO INSTRUCTIONS 


Access method services may also be invoked via a LOAD of the 
module IDCAMS, followed by a CALL to that module. The format of 
the LOAD macro instructicn is: 


[name] LOAD | {EP=IDCAMS|EPLOCtaddress of name} 


where: 


EP=IDCAMS 
is the entry point name of the IDCAMS program to be loaded 
into virtual storage. 


EPLOC=address of name 
is the address of an 8~-byte character string "IDCAMS bb’. 


After loading IDCAMS, register 15 must be loaded with the 
address returned from the LOAD macro. Then CALL may be used to 
pass control to IDCAMS. The format of the CALL macro 
instruction is: 





where: 


15 


is the register containing the address of the entry point 
to be given control. 


specifies the address of an options list that can be 
specified in the PARM parameter of the EXEC statement and 
1S a valid set of parameters for the access method services 
PARM command. If you do not want to specify any options, 
this address must point to a halfword of binary zeros. 
Figure 24 on page 322 shows the format of the options list. 


specifies the address of a list of alternate dd names for 
standard data sets used during IDCAMS processing. If 
standard ddnames are used and this is not the last 
parameter in the list, it should point to a halfword of 
binary zeros. If it is the last parameter, it may be 
omitted. Figure 24 shows the format of the alternate 
ddname list. 
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panoaddr 


specifies the address of a 6-byte area that contains an 
EBCDIC starting page number for the system output file. If 
the page number is not specified, but this is not the last 
parameter in the list, the parameter must point to a 
halfword of binary zeros. If it is the last parameter, it 
may be omitted. If omitted, the default page number is l. 
Figure 24 on page 322 shows the format of the page number 
area. 


specifies the address of a list of externally controlled 
data sets and the addresses of corresponding I/0 routines. 
If no external I/0 routines are supplied, this parameter 
a omitted. Figure 24 shows the format of the I70 
ist. 


VL 
causes the high-order bit of the last address parameter in 
the macro expansion to be set to 1 


INVOCATION FROM A PL/I PROGRAM 


Access method services may also be invoked from a PL/I program 
using the facilities of the IBM PL/I Optimizing Compiler 
Licensed Program. IDCAMS must be declared to the compiler as an 
external entry point with the ASSEMBLER and INTER options. The 
access method services processor is loaded by issuing a FETCH 
IDCAMS statement, is branched to via a CALL statement, and 
deleted via a RELEASE IDCAMS statement. The format of the CALL 
statement is: 


CALL =|: IDCAMS (optionsl,dnamesl[,pagenoll[ »iolisti); 


where: 


specifies a valid set of parameters for the access method 
services PARM command. If no parameters are to be 
specified, options should be a halfword of binary zeros. 
Figure 24 on page 322 shows the format of the options area. 


dnames 


specifies a list of alternate ddnames for standard data 
sets used during IDCAMS processing. If standard ddnames 
are used and this is not the last parameter in the list, 
dnames should be a halfword of binary zeros. If it is the 
last parameter, it may be omitted. Figure 24 shows the 
format of the alternate ddnames list. 


Pageno 


specifies a 6~-byte field that contains an EBCDIC starting 
page number for the system output file. If the page number 
is not specified, but this is not the last parameter in the 
list, the parameter must be a halfword of binary zeros. If 
it is the last parameter, it may be omitted. If not 
specified, the default page number is 1. Figure 24 shows 
the format of the page number area. 


specifies a list of externally controlled data sets and the 
addresses of corresponding I/0 routines. If no external 
I/0 routines are supplied, this parameter may be omitted. 
Figure 24 shows the format of the I/0 list. 
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REG 1 











OPTIONS LIST 


| : LENGTH OPTIONS 
ARGUMENT LIST | 


. OPTIONS OPTIONS LIST: Required. Provides a 


| 


LIST 


way to specify processing options. If 


é DDN AMES | you do not wish to specify any options, 


you must set the LENGTH field to 


LIST | binary zeros. 


— > 


LIST 


PAGE NUMBER LENGTH: Halfword that specifies the 


number of bytes in the OPTIONS field. 


IOLIST OPTIONS: Character string that con- 


FE 


tains the processing options of the access 
method services PARM command. The 
options may be specified in the PARM 
PAGE NUMBER LIST field of the EXEC statement or they may 


| be set up by the problem program. The 
LENGTH options must comply with the parameter 
ae syntax of the access method services 


PAGE NUMBER LIST: Optional. Provides 
a way to specify the starting page number 
for system output. 


LENGTH: A halfword that specifies the number 
of bytes in the PAGE NUMBER field. 


PAGE NUMBER: 1- to 4-byte character string that 

may specify the starting page number of system output 

listing. This value is reset to the current page number DDNAMES LIST 

upon completion of the present invocation of the DDNAMES LIST: Op- 


access method services processor. | LENGTH 
(2 bytes) 


tional. Provides a way to 
specify alternative names 


& INPUT/OUTPUT LIST binary zeros for the SYSIN and 
INPUT/OUTPUT LIST: Optional. Provides the means of 
identifying those data sets for which the invoker wishes to. binary zeros LENGTH: Halfword that 
. manage all I/O operations. (8 bytes) specifies the number of 
4 : bytes in the remainder 
DDNAME, n: A fullword that specifies the number of groups of three binary zeros | of the list. 
fields that follows. Each group consists of aDDNAME address, (8 bytes) 


ie 


a USER DATA, 


iy 
ij 





> 


—i 


Figure 


| ® IOROUTINE, 


DDNAME,, 


4 IOROUTINE,, 
USER DATA, 







24. 


an IOROUTINE address, and a USER DATA address. DDNAMES: Unseparated 


binary zeros | 3.character ddnames, left- 


DDNAME: Address of a character string that identifies a ( 8 bytes ) justified, and padded with 
data set that will result in the invocation of the associated blanks. To change the 
IOROUTINE for all 1/O operations (including OPEN and SYSING66 name of SYSIN or 
CLOSE) against the data set. The character string identifies -SYSPRINT, supply an 
the data set as either a 10-byte or 46-byte character string alternate name in the 

as follows: same position. If an 


alternate name is not 
supplied, the standard 
name is assumed. If the 
name is not supplied 
with the list, the 8-byte 
entry must contain 
binary zeros. Names in 
any position other than 
A 46-byte character string: The first two characters are those for SYSIN and 
‘DS’, the next 44 characters are the data set name, left- SYSPRINT are ignored. 
justified (padded with blanks if necessary), which may appear 

in the INDATASET, OUTDATASET, or DATASET para- 

meters of any access method services command. 


A 10-byte character string: The first two characters are ‘DD’, 
the next 8 characters are the DDNAME field value 
left-justified (padded with blanks if necessary), which may 
appear in the FILE, INFILE, or OUTFILE parameters of any 
access method services command. The SYSIN and 
SYSPRINT ddnames may also appear if the invoker wishes 

to manage these data sets. 


IOROUTINE: Address of the program that is to be invoked 
to process I/O operations upon the data set associated with 
DDNAME.. This routine, instead of the processor, will be 
invoked for all operations against the data set. See “User 
I/O Routines” in this appendix for linkage and interface 
conventions between the IOROUTINE and access method 
services. 


USER DATA: Address of a data aréa user may use for any purpose. 


Processor Invocation Argument List from a Problem Program 
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C 
a ps 
i \ 
Sy 7 we 
ee 























PROCESSOR INVOCATION 


PROCESSOR CONDITION 


Figure 24 on page 322 shows the processor invocation argument 
list as it exists in the user's area. 


Entry and exit to the access method services processor occurs 
through IDCSA01, a module of the system adapter. Standard 
linkage is used; that is, register 1 points to the argument 
list, register 13 points to a save area, register 14 contains 
the return address, and register 15 contains the entry point 
address for IDCSA01]. On exit from the access method services 
processor, register 15 contains the value of MAXCC (see 
"Processor Condition Codes" later in this appendix). 


The argument list, as shown in Figure 24%, can be a maximum of 
four fullword addresses pointing to strings of data. The last 
address in the list contains a "1" in the sign field. The first 
three possible strings of data begin with a 2-byte length field. 
A null element in the list can be indicated by either an address 
of zeros or a length of zero. 


CODES 


The processor's condition code is LASTCC, which can be 
interrogated in the command stream following each functional 
command. The possible values, their meanings, and examples of 
causes are: 


Code Meaning 


0¢0) The function was executed successfully. Informational 
messages may have been issued. 


4(4) Some minor problems in executing the complete function 
were encountered, but it was possible to continue. The 
results may not be exactly what the user wants, but no 
permanent harm appears to have been done by continuing. 
A warning message was issued. 


8(8) A function could not perform all that was asked of it. 
The function was completed, but specific details were 
bypassed. 

12(€C) The entire function could not be performed. 

16(€10) Severe error or problem encountered. Remainder of 


command stream is flushed and processor returns 
condition code 16 to the operating system. 


LASTCC is set by the processor at the completion of each 
functional command. MAXCC, which can also be interrogated in 
the command stream, is the highest value of LASTCC thus far 
encountered. 


User I/70 routines enable a user to perform all I/0 operations 
for a data set that would normally be handled by the access 
methods services processor. This makes it possible, for 
instance, to control the command input stream by providing an 
tT ata for SYSIN. As pointed out above, standard linkage is 
used. 


A user [70 routine is invoked by access method services for all 
operations against the selected data sets. The identification 
of the data sets and their associated I/0 routines is via the 
input/output list of the processor invocation parameter list 
(see Figure 24 on page 322). ; 


When writing a user I/O routine, the user must be aware of three 
things: First, the processor handles the user data set as if it 
were a non-VSAM data set that contains variable-length unblocked 
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records (maximum record length is 32760 bytes) with a physical 


sequential organization. The processor does not test for the aa 
existence of the data set. Second, the user must know the data | ‘ 
format so that the routine can be coded to handle the correct ee 


type of input and format the correct type of output. Third, 
each user routine must handle errors encountered for data sets 
it is managing and provide a return code to the processor in 
register 15. The processor uses the return code to determine 
what it is to do next. 


The permissible return codes are: 


Code Meaning 

0€0) Operation successful. 

4049) End of data for a GET operation. 

&8C8) Error encountered during a GET/PUT operation, but 


continue processing. | 


12¢€C) Do not allow any further calls (except CLOSE) to this 
routine. 


Figure 25 on page 325 shows the argument list used in 
communication between the user I/0 routine and the access method 
services processor. The user I/0 routine is invoked by the 
processor for OPEN, CLOSE, GET, and PUT routines. 


The type of operation to be performed is indicated via IOFLAGS. 
The IOQINFO field indicates, for OPEN and CLOSE operations, the 
data set name or ddname of the data set; for GET and PUT 
operations, the IOINFO field is used to communicate the record 
length and address. 


A user I/0 routine for SYSPRINT receives control each time the 
processor issues a PUT against the SYSPRINT data set. If the 7 
PUT has been issued to print an IDC message, the unique message ed 
number is passed to the routine via IOFLAGS (see Figure 25 aon 

page 325). Each IDC message is in the form IDCsnnnI or 

IDCsnnnni, where: 


S 18S a code indicating the severity of the problem. 


nnn or nnnn is the message number that 1s unique across all 
IDC messages. 


The 2-byte message number passed via IOFLAGS is the nnn or nnnn 
portion of the message converted to binary. 
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GET or PUT 


Record Length 


For a GET, this information 
is returned to the processor 
by the user’s I/O routine in 
the 8-byte area passed to the 
routine. 


for a PUT, the processor 
gives this information to the 
user's I/O routine. 


Record (GET): Address of 
retrieved record. 


Record Length (GET): Full- 
word length of retrieved 
record. 


Record (PUT): Address of 
record to be written. 


Record Length (PUT): Full- 
word length of record to be 
written. 


Figure 25. 


Appendix E. 








USER DATA 
IOFLAGS 


A IOINFO 


OPEN 


DDNAME or 
DATASETNAME 


DDNAME: 8-byte field, left- 


justified (padded with blanks if 


necessary) containing the 
ddname. 


DATASETNAME: 44-byte field 
(padded with blanks if necessary) 
containing the data set name. 


CLOSE 


A Data Set Name 


DATASETNAME 


DATASETNAME: 44-byte 
field (padded with blanks 
if necessary) containing 
the data set name. 





User data pointer obtained from the 
input/output list of the processor 
invocation parameter list. 


FLAGS 


Value or 
Fullword of Flags: Bit Pattern 
Byte 1 X‘00’ 
(Operation) X‘04’ 
x‘08’ 
x‘0Cc’ 
Byte 2 Dishes, ees 
phe dks 
Sr 
Bytes 3,4 0 
(Record type 
for PUT only) 
n 


Arguments Passed to and from a User I/0 Routine 








Meaning 


OPEN 
CLOSE 
GET 
PUT 


OPEN for input 

OPEN for output 
Indicates IOINFO 
contains the address 
of a ddname on OPEN. 


Indicates IOINFO contains 
the address of a data set 
name on OPEN. 


Normal data record is to 
be written. 


Message serial number 
converted to binary if 
IDC message is to be 
written. (See “User I/O 
Routine”’ for a description 
of this value.) 
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whez? 











This appendix shows the format of each access method services 
functional command, parameter abbreviation, and default. The 
commands are grouped together to allow you to remove these pages 


and use them for a quick reference. 


0 PREVIOUSLY DEFINED CATALOG 


ALTER 


entrynamel/password] 
[ADDVOLUMES(volser[ yolser...1])] 
CATTEMPTS (number J] 


[AUTHORIZATIONCentrypoint€ string])] 


[BUFFERSPACE(size)1 
[CODE(code)] 
[CONTROLPW(password)1] 

[ DESTAGEWAIT | NODESTAGEWAIT] 
[EMPTY |NOEMPTY] 
[ERASE | NOERASE] 
[TEXCEPTIONEXIT(entrvypoint)1 
CFILE(ddname)1] 


[FREESPACE(CI-percent£ CA-percent])] 


{LINHIBIT|UNINHIBIT] 

[KEYS ( offset 

PAS TERPWleassword) 1 

[NEWNAME (newname)] 

C[NULLIFY( 
f[AUTHORIZATION( MODULE |STRING)I 


[CODE] 
[CONTROLPW] 
[EXCEPTIONEXIT] 
C[MASTERPW] 
[OWNER] 
[READPW] 
[RETENTION] 
[UPDATEPW] )] 
[OWNER (ownerid)] 
[LREADPW( password) ] 
CRECORDSIZElaverage 


maximum) 1] 
[CREMOVEVOLUMES(volser[ volser...1)] 
crosssystem1)] 


- ESCRATCH|NOSCRATCH] 
CSHAREOPTIONS(crossregionl 
[STAGE (| BIND|CYLINDERFAULT] 
[TO(l date) |FOR(days)] 
[UNIQUEKEY | NONUNIQUEKEY] 
[UPDATE |NOUPDATE] 
CLUPDATEPW(password)1 
[UPGRADE | NOUPGRADE ] 
CWRITECHECK | NOWRITECHECK] 


[CATALOG( catnamel /password] )] 
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AUTH 
BUFSP, BUFSPC 


CTLPW 

DSTGW NDSTGW 
EMP NEMP 
ERAS NERAS 
EEXT 

FSPC 

INH UNINH 


MRPW 
NEWNM 
NULL 
AUTH MDLE 
STRG 
CTLPW 
EEXT 
MRPW 
RDPW 
RETN 
UPDPW 


RDPW 


UNQK NUNQK 
UPD NUPD 
UPDPW 

UPG NUPG 
WCK NWCK 


CAT 











we 





Pol 




















Parameters 


BLDINDEX 

CINFILE(ddnamel /password| )I 

INDATASETlCentrynamel ‘password! }4 
TOUTFILE(ddnamel/password! 

[ ddnamel/pass sword]. ..1)1 

OUTDATASET Centrynamel /password] 

[ entrynamel /password!. »-1}4 

[CATALOG( catnamel/password]) CAT 
[TEXTERNALSORT | INTERNALSORT1 ESORT ISORT 
[WORKFILES(ddname ddname)] WFILE 


Parameters 


CHKLIST 
INFILE(ddname) 
[CHECKID( checkid...)] 
[OUTFILE(ddname)1] 


( 7 I CNVTCAT 
i CINFICE (ddnamel /password| 


iI 
[ INDATASET Centrynamel /password]}} 
SD Cea 


CCVOLEQUATES( (catname 

volser...1))} (catname...J)..--1)] 
[LIST|INOLIST] 
[MASTERCATALOG( catnamel /password1])1 
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DEF 


DEFINE 
ALIAS 


(NAME Caliasname) 
RELATECentryname)) 


[CATALOG( catnamel /password])1 


AAU ae Pe, 4 Wer Sie Ff ATALY EIN TK JI AN ALIERINGA 


DEFINE ALTERNATEINDEX 
(NAME ( ryname) 

RELATE Centrynamel /password)) 
{CYLINDERS! (primaryl secondary] }| 
RECORDS! (primaryl secondaryj)| 

TRACKS? ( secondary] )} 
VOLUMES2@(volserl volser...1!) 
CLATTEMPTS (number ![2)1 
[AUTHORIZATION( entrypointl 
[BUFFERSPACE(size)] 

[CODE(code)] 

aE ar Ui ieee tara ee 
[CONTROLPW( password) ] 

IDESTAGEWATT [NODESTAGEWAIT) 
[ERASE |NO E] 
LEXCEPTIONEXITCentryvpoint)] 
[FILE€Cddname) 1] 

[ FREESPACE(CI- CA-percent]10 9) 
[IMBED | NOIMBED] 
[KEYRANGES( (lowkey 

[ (lowkey hishkey) 
{KEYS (lenath 
 HASTERPH eweseeeaht 
[MODELCentrynamel /password] 

[ ca [/password1])]1 
LORDERED | UNORDEREDI 
[LOWNER( ownerid)] 

[READPW( password) ] 
TRECORDSIZE(average maximum| 

4086 32600)] 
[REPLICATE | NOREPLICATE] 
[REUSE | NOREUSE] 

[SHAREOPTIONS (crossregion 

[ crosssystem]11 3)] 
[SPEED[ RECO ] 

[STAG Bee eC atoeReaures 

[TOldate) | FOR(davs)] 

[UNIQUE | SUBALLOCATION] 

CUNIQUEKEY | NONUNIQUEKEY] 

C[UPDATEPW( password) ] 

[UPGRADE |NOUPGRADE] 
CWRITECHECK | NOWRITECHECK] ) 


}] 
Q)] 


ood 
offset 164 


(Continued; notes follow) 
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LNVE 


REL 
CAT 





DEF AIX 


AUTH 
BUFSP, BUFSPC 
CISZ, CNVSZ 
CTLPW 


DSTGW NDSTGW 
ERAS NERAS 
EEXT 


FSPC 
IMBD NIMBD 
KRNG 


ORD UNORD 


RDPW 
RECSZ 


REPL NREPL 
RUS NRUS 
SHR 


—— RCVY 
ome oe COLL 
UNQ SUBAL 
UNQK NUNQK 
UPDPW 

UPG NUPG 
WCK NWCK 














eA 


earn 














[DATA 


(CATTEMPTS (number J] 
[AUTHORIZATION(entrypoint£ string])] 
[BUFFERSPACE(size)] 

[CODE(code)] 

[ CONTROLINTERVALSIZE(size)1 
[LCONTROLPW( password)] 
[CYLINDERS(primarvE€ secondary])| 
RECORDS(primaryf secondary] )}| 
TRACKS(primaryl secondaryl)] 
[DESTAGEWALIT | NODESTAGEWAIT] 
[ERASE |NOERASE] 

pE e CEP EL ONENt) tenseveornt)? 
EFILE(ddname X *%)] 
C[FREESPACE(CI-percentl CA-percent!)] 
[KEYRANGES(Clowkey highkey) 
[(lowkey highkey]...1)] 
CKEYS(length offset)] 
PAS TERPWieassword) 1 
[MODEL entrynamel/password] 

[ catnamel /password]1}1 

CNAME Centryname)] 
SOHER Coho aaa 

[OWNER( ownerid)] 
[CREADPW( password) 1 
TRECORDSIZEl(average maximum)] 
[REUSE | NOREUSE] 


[SHAREOPTIONS(crossregionl crosssystem])1] 


[SPEED] RECOVERY] 
CSTAGE|BIND|CYLINDERFAULT] 
[UNIQUE | SUBALLOCATION] 

Tt at lethet robe ica 
[UPDATEPW( password) ] 
CVOLUMES(volser[ volser...1)] 
[WRITECHECK | NOWRITECHECK] )1 


(Continued; notes follow) 


e 
‘ bed : 


Parameters 


ATT 
AUTH 
BUFSP, BUFSPC 


CISZ, CNVSZ 
CTLPW 


DSTGW NDSTGW 
ERAS NERAS 
EEXT 


wane 


FSPC 
KRNG 


ORD UNORD 


RDPW 
RECSZ 


YLF 
UNQ SUBAL 
UNQK NUNQK 
UPDPW 


VOL 
WCK NWCK 
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OTe 








Parameters 


[INDEX 
(CATTEMPTS (number J] 


[TAUTHORIZATION(Centrypointl string]}] 


[CODE (code)] 

PeOIAROLS eae ae 
[CONTROLPW( password) ] 
[CYLINDERS(primary£ secondary])| 
RECORDS(primaryi secondary!) | 
TRACKS(primaryvl secondary] )} 
[DESTAGEWALT |NODESTAGEWATT 
CEXCEPTIONEXITlentrypoint)] 
[FILE(ddname)] 

[IMBED|NOIMBED] 


entryname]) 
[ORDERED | UNORDERED] 
[OWNER(Cownerid)] 
C[READPW( password) ] 
[REPLICATE | NOREPLICATE] 
[REUSE | NOREUSE] 


[SHAREOPTIONS(crossregionl crosssystem])1 


[STAGE|BIND[CYLINDERFAULTI 

Dyed peter a aeipeebeai 
[UPDATEPW( password)] 
[VOLUMES(volserl{ volser...])] 
C[WRITECHECK [NOWRITECHECK] )] 


[CATALOG( catnamel/password])] 





Notes 


CYLINDERS, RECORDS, or TRACKS must be specified either as a 
parameter of ALTERNATEINDEX, as a parameter of DATA, or as a 
parameter of both DATA and INDEX if MODEL is not specified. 


VOLUMES must be specified as a parameter of ALTERNATEINDEX 
or aS a parameter of both DATA and INDEX if MODEL is not 


| 


specified. 
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IX 

ATT 

AUTH 

CISZ, CNVSZ 
CTLPW 

CYL 

REC 


TRK 
DSTGW NDSTGW 
EEXT 


IMBD NIMBD 
MRPW 


ORD UNORD 


RDPW 

REPL NREPL 
RUS NRUS 
SHR 

Soe ee OY LE 
UNQ SUBAL 
UPDPW 

VOL 

WCK NWCK 


CAT 


yon 




















» e 45 » 
LNG F ALALY AvaE, Vit A AM ULVOIEN 


DEFINE CLUSTER 

(NAME ( ) 

{CYLINDERS! (primary€ secondary])| 
RECORDS! (primary£ secondary])| 
TRACKS! (primary£ secondary] )} 

VOLUMES@(volser[ volser...1) 

LATTEMPTS(number|2)] 

C[AUTHORIZATION( entrypointl£€ string] )1 

C[BUFFERSPACE(size)] 

[CODEl(code)] 

C[CONTROLINTERVALSIZE(size)1 

[CONTROLPW(password)] 

[DESTAGEWATT INODESTAGEWAIT} 

[ERASEINO 

Fey CED PIONERET Canaan 

CFILE(ddname)I 

E Chvperce 


119 ON 

C[IMBED| 

INDEXEW | NONENDEXED | NUMBERED) 
[KEYRANGES¢( (lowkey i ) 

[Clowkey highkey)...1)] 
[KEYS? (length offset | 8% Q)] 
[MASTERPW( password)] 
Peete Lfentrynanel /paseword] 

catnamel password) 4 

rORDERED | UNORDERED 
[OWNER(ownerid)] 
[READPW( password)] 
[RECORDSIZE‘ (average maximum)] 
[REPLICATE | NOREPLICATE]> 
[REUSE |[NOREUSE] 
[SHAREOPTIONS(crossregion 

[ crosssysteml|1 3)1 
[ SPANNED | NONSPANNED J 
[SPEED | RECOVERY] 
[STAGE | BIND| CYLINDERFAULT]I 
[TOC date) | FOR(days)] 
[UNIQUE | SUBALLOCATION] 
[UPDATEPW( password)] 
[WRITECHECK | NOWRITECHECK] } 


CContinued; notes follow) 


TH 
BUFSP, BUFSPC 
CISZ, CNVSZ 
CTLPW 
DSTGW NDSTGW 
ERAS NERAS 
EEXT 
FSPC 


IMBD NIMBD 
IXD NIXD NUMD 
KRNG 


MRPW 


ORD UNORD 
RDPW 

RECSZ 

REPL NREPL 
RUS NRUS 
SHR 

SPND NSPND 
—~- RCVY 
ee ee CLL 
UNQ SUBAL 
UPDPW 

WCK NWCK 
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DATA 
CLATTEMPTS (number )1 


[LAUTHORIZATION(entrypoint£ string])] 
[BUFFERSPACE(size)1 

[CODE(code)] 

FET et iota trate 
CCONTROLPW( password)] 

[CYLINDERS (primarvl 

RECORDS (primaryl secondary)! 
TRACKS(primarv[ secondary])1 
[DESTAGEWAIT |NODESTAGEWAIT I 

[ERASE |NOERASE] 
CEXCEPTIONEXITCentrypoint)] 
[FILE€(ddname)J] 

[FREESPACE=(CI-percentl cA-pereent!)) 
[KEYRANGES?(Clowkey highkey) 

[Clowkey highkey)...1)] 

[KEYS? (length offset) 

CMASTERPW {password ) ] 

[MODEL Centrynamel/ 

[ cainanel /password!1)3 


entrynane 
CORDERED | UNORDERED] 
LOWNER(Cownerid)1 
CREADPW( password) ] 
C[RECORDSIZElav 
[REUSE |[NOREUSE] 
[SHAREOPTIONS ( 
[SPANNED | NONSPANNED] 
[SPEED|RECOVERY] 
[STAGE |BIND|CYLINDERFAULT] 
A a gaara 
[CUPDATEPW( password) ] 
[EVOLUMES(volserlf volser...1)] 
[WRITECHECKINOWRITECHECK] } 1] 


maximum) 1] 


CContinued; notes follow) 
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crosssystem])] 





ATT 
AUTH 


BUFSP, BUFSPC 


CISZ, CNVSZ 
CTLPW 

CYL 

REC 


TRK 

DSTGW NDSTGW 
ERAS NERAS 
EEXT 


Sparse 


FSPC 
KRNG 


ORD UNORD 


RDPW 

RECSZ 

RUS NRUS 
SHR 

SPND NSPND 
—— RCVY 
oe ee (CV LE 


UNQ SUBAL 
UPDPW 


VOL 
WCK NWCK 














‘Parameters 


[INDEX 
CLATTEMPTS (number )1 





IX 
ATT 


CAUTHORIZATION(entrypointl string])] AUTH 


[CODE( code 
C[CONTROLINTERVALSIZE(size)] 
C[CONTROLPW( )] 


CISZ,CNVSZ 
CTLPW 


[CYLINDERS(primarvl[ secondary])] CYL 
RECORDS (primaryl secondary!) | 

TRACKS(primarv£ secondary])1] 

[DESTAGEWATT |NODESTAGEWATT 
[EXCEPTIONEXITlentrypoint)] 
[FILE(ddname)] 
[IMBED|NOIMBED] = 


PIAS TERPW i password) 
CMODELCentrynamel/ 

[ catnamel /password)1)1 
[NAME Centryname)] 

[ORDERED] UNORDERED] 

[OWNER (ownerid)] 
[READPW( password) ] 
[REPLICATE |NOREPLICATE]> 
[REUSE | NOREUSE] 


DSTGW NDSTGW 
EEXT 


IMBD NIMBD 
MRPW 


ORD UNORD 


RDPW 
REPL NREPL 
RUS NRUS 


[SHAREOPTIONS(crossregionl crosssystem])!1 SHR 


[STAGE!BIND|CYLINDERFAULT] 
[UNIQUE | SUBALLOCATION] 
PUP ATER W (password) ] 


[VOLUMES(volserl olser...1)] 


[WRITECHECKINOWRITECHECKI D1 
[CATALOG( catnamel /password])] 


Notes 


CYLINDERS, RECORDS, or TRACKS must be specified either as a 
parameter of CLUSTER, as a parameter of DATA, or as a 
parameter of both DATA and INDEX if MODEL is not specified. 


| 


ae ome CY LE 
UNQ SUBAL 
UPDPW 

VOL 

WCK NWCK 
CAT 





VOLUMES must be specified as a parameter of CLUSTER or as a 
parameter of both DATA and INDEX if MODEL is not specified. 


Can only be specified for a key~sequenced cluster. 


When SPANNED is specified, the default is RECORDSIZE 
(4086 32600). Otherwise, the default is RECORDSIZE 


C4089 4089). 
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Parameters 


DEFINE GENERATIONDATAGROUP DEF GDG 
CNAME entryname ) — 
LIMIT (ClLimit ) LIM 
CEMPTY|NOEMPTY1] EMP NEMP 
[OWNER(ownerid)1 — 
[SCRATCH | NOSCRATCH] SCR NSCR 
[TOC date) | FOR(days)1) arco 


[CATALOG( catnamel /password1)] 


Parameters 
DEFINE NONVSAM 
(N ( 


AME Centryname 
DEV ECE TYPES (devtveel devtype...1J) 
VOLUMES (vo ) 


volserl 
[FILESEQUENCENUMBERS (nunber 


[OWNER ( ownerid)1 
[TO( date) |FOR(da ved) 


[CATALOG( catnamel /password])] 


Parameters 


DEFINE PAGESPACE 
(NAME Centryname) 
{CYLINDERS (primary) | 
RECORDS (primary) | 
TRACKS (primary )} 
VOLUME (volser 3} 
CATTEMPTS (number 12)1 


CAUTHORIZATION(entrvpointl( string])1 
[CODE(code)1 


C[FILE(ddname)] 

aaa PeRPWlpassword)} 

(HODEL Centrynamel /password] 
TF catnamel cpassword]1}4 
[OWNER (Cownerid)] : 


! NOSWAP 
[TOldate) | FOR( days) 
[UNIQUE | SUBALLOCATION] UNQ SUBAL 
[UPDATEPW( password)]) UPDPW 


[CATALOG( catnamel /password])1 CAT 
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Parameters 


DEFINE PATH 
(NAME Centryname ) 
PATHENTRY Centrynamel /password] } 
CLATTEMPTS (number 12)1] 
CAUTHORIZATION(entrypointl string])] 
[CODE(code)] 
[CONTROLPW( password)] 
[FILE(ddname)] 
[MASTERPW( password) ] 
[MODEL(entrynamel /password] 
[ catnamel/password]1)] 
[OWNER( ownerid)] 
[READPW( password) ] 
[TO( date) |FOR(days)] 
[UPDATE |NOUPDATE] | UPD NUPD 
[UPDATEPW( password)]) UPDPW 


[CATALOG(catnamel/password])]1 CAT 





DEFINE SPACE | DEF SPC 
(LCANDIDATE | CAN 
CYLINDERS (primarvl 1) CYL 
RECORDS (primaryvl 
( VOLUMES(volserL volser...1) 
™ [FILE(ddname)]) 


[CATALOG( catnamel/password] )1 
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secondary] ) | 


TRACKS(primary£ secondary4J)} 


VOLUME(volser ) 


[ATTEMPTS (number 12)] 


[AUTHORIZATION entrypointl 


[BUFFERSPACE(size|13072)]1 


[CODE(code)] 


[CONTROLPW( password) ] 
[DESTAGEWAIT | NODESTAGEWAIT1 


[FILEC(ddname) 1 


PM AS TERPW (password) J 


1 catnanat/pass 


catname 
[OWNER (ownerid)1 


[READPW( password)] 


/password] 
1)] 


[RECORDSIZElaverage maximum)] 
[RECOVERABLE [NO paseoubane ERABLE] 
(TOl( date) | FOR(days)] 
[UPDATEPW( password) ] 


[WRITECHECK | NOWRITECHECK] ) 
[DATA 


( LBUFFERSPACE(size)] 


TRACKS [ 


Primary[ secondary] 
[DESTAGEWAIT | NODESTAGEWAIT] 


[RECORDSIZE lave 


[CYLINDERS(primaryl£ secondary]) 
RECORDS (primaryl 


secondary])| 


average maximum 
[RECOVERABLE | NOTRECOVERABLE] 
[WRITECHECK | NOWRITECHECK]) )] 


C INDEX 


(£CYLINDERS( primary) | 


RECORDS(primary )| 


TRACKS ( 


primary)] 
[DESTAGEWAIT | NODESTAGEWAITI 
[WRITECHECK | NOWRITECHECK])] 


[CATALOG(mastercatnamel /password])1 


it 


secondary1]}| 


yuga 
wT 


string])] 
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DEF UCAT MCAT 
CYL 
REC 
TRK 
VOL 
ATT 
AUTH 
BUFSP, BUFSPC 


CTLPW 
DSTGW NDSTGW 
MRPW 


RDPW 
RECSZ 

RVBL NRVBL 
UPDPW 

WCK NWCK 


BUFSP, 
CYL 
REC 
TRK 
DSTGW NDSTGW 
RECSZ 


RVBL_ NRVBL 
WCK NWCK 


IX 


BUFSPC 


CYL 


REC 

TRK 

DSTGW NDSTGW 
WCK NWCK 


CAT 











| oo 
Parameters SSSCSCSCSCS~d wd 


DEFINE USERCATALOG | MASTERCATALOG 
(NAME Centryvname) 
{CYLINDERS (primarvl 
RECORDS (primaryvl 


be | 
ee” 








a 








DEL 


[/password] 
[/password]...]J) 
ALIAS | 
ALTERNATEINDEX | 
CLUSTER] 


GENERATIONDATAGROUP | 
NONVSAM | 


PAGESPACE | 

PATH] 

SPACE? | 

USERCATALOG? } 

[ ERASE | NOERASE ] ERAS NERAS 
[FILE(ddname)] — 

[FORCE | NOFORCE] FRC NFRC 

[ PURGE | NOPURGE] PRG NPRG 

[ SCRATCH | NOSCRATCH] SCR NSCR 


C[CATALOG( catnamel /password])] CAT 





Notes 


3 When you delete a data space or catalog, you cannot delete 
any other type of entry. You must identify the type of 


entry to be deleted, by specifying SPACE or USERCATALOG. 


EXAMINE sacs 
NAME (cluste rnamel/password]) SS a 
c ST|NOINDEXTEST1 ITEST NOITEST 


[DATATEST | NODATATEST] DTEST NODTEST 
CERRORLIMIT(value)] ELIMIT 


Parameters 


EXPORT 
usercatnamel/password] 
DISCONNECT 


EXPORT EXP 


entrynamel /password! = 
POUTFILE(ddname} |OUTDATASET(entryname )3 OFILE ODS 
CINFILE( ddname)1] IFILE 


[ERASE | NOERASE1 ERAS NERAS 


[ INHIBITSOURCE | NOINHIB TTSOURCE} INHS NINHS 
[INHIBITTARGET | NOINHIBITTARGET] INHT NINHT 
[ PURGE | NOPURGE] PRG NPRG 

CTEMPORARY | PERMANENT] TEMP PERM 
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Parameters 


/EXPORTRA 
OUTFILE(ddname) 
CRA[ 
(ddnamel 
{ALLE INFILE(ddname2)]1]| 
ENTRIES( 
( [ ddname3]) 
C[Centrynamel ddname3])...1)] 
NONE} ) 
ameleceJeeeo ld) 
[FORCE |NOFORCE] FRC NFRC 
[MASTERPW(password)] MRPW 


Parameters 


IMPORT _ 

CONNECT 

OBJECTS ((usercatname 
DEVICETYPE(devtype]) 
VOLUMES (volser))) 


[CATALOG(mastercatnamel /password])] 





» ° : ’ 2 , ‘ 
[MPORT-—RESTORE A AM CLUSTER OR ALTERNATE INDEX FROM A PORTABLE DATA SET CREATED ee 


Parameters 
IMPORT 





EINFILE( ddname } | INDATASET (entryname )} 
{LOUTFILE(ddnamel/password]) 
OUTDATASET Centrynamel /password) }} 
[ERASE | NOERASE] 
[INTOEMPTY] 
rOBVECTS (Centryname 
[FILE(ddname)] 
[KEYRANGES(Clowkey hiaqghkey) 
[Clowkey highkey)...1)] 
_[TNEWNAME (newname )1 
Oh ten, uNOnveReD? 
C[VOLUMES(volser yolser.++1}1) 
Plenteunne eat 
[ PURGE | NOPURGE] 
[SAVRAC | NOSAVRAC] 


| [CATALOG(catnamel /password])] 
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IMP 

IFILE IDS 
OFILE 

ODS 

ERAS NERAS 
IEMPTY 

OBJ 


scmeaammtaniatedl 


KRNG 
NEWNM 

ORD UNORD 
VOL 


PRG NPRG 


CAT 























Parameters 


IMPORTRA 


MPRA 
LINFILE( ddname) | INDATASET(entrvname )} IFILE IDS 
[COUTFILE( ddname)] OFILE 
pb ictal OBJ 


entryname 
PDEVICE TYPES (dev tvpel devtype...1)] DEVT 


ddname) 


[ ents note 
[SAVRAC | NOSAVRAC 1] 
[CATALOG( catnamel /password1])] 


Parameters 


LISTCAT 
CENTRIES (entrynamel /“password] 
[ entrynamel/password]...1)] 
LEVEL( level)] 
[ALIAS] 
ALTERNATEINDEX] 
CLUSTER] 
DATA] 
a, GENERATIONDATAGROUP] 
( INDEX] 
NONVSAMN] 


PAGESPACE] 

PATH] 

SPACE] 

USERCATALOG] 
[CREATION( days) ] 
PETER TON days JI 


CNAME | 
HISTORY | 
VOLUME | 
ALLOCATION | 
ALL] 


[NOTUSABLE] 
[OUTFILE( ddname)1] 


[CATALOG( catnamel /password])1]1 


LISTR 
IFILE 
CAT 
[COMPARE | NOCOMPARE ] CMPR NCMPR 
oe peas | SEQUENT ALDUNE? 
[MASTERPW( password) 1] 
rQUTFILE{ deer 
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PRINT 
CINFILE(ddnamel “password! }| 


INDATASET Cenkrynanel /password])} 
[OUTFILE(ddname)] 


ECHARACTER | DUMP | HEX] 

[ FROMKEY (key) | FROMADDRESS (address) | FKEY FADDR 
FROMNUMBER( number ) ISKIP(count)] FNUM —— 

[TOKEY (key) | TOADDRESS (address) | | —~- TADDR 
TONUMBER (number J [COUNT(count)] TNUM — | 





REPRO~~COPY DATA SETS OF [INTEGRATED CATALO ACILI 


Parameters 


REPRO 
CINFILECddnamel /password] 
[ ENVIRONMENTC DUMMY ))) | 
INDATASET (entrynamel /password 
[ ate ihaataliea iene laELdE 
CLOUTFILE(ddnamel “password! } 
OUTDATASET (entrvnamel /password] )} 
[DECIPHER 
(IDATAKEYFILE( ddname} | 
DATAKEYVALUE (value) | SYSTEMKEY] DKV SYSKEY 
[SYSTEMDATAKEY (value) ] SYSDK 
[SYSTEMKEYNAME (keyname)1) 1] SYSKN 
C[ENCIPHER | ENCPHR 
(CEXTERNALKEYNAME (keyname) | EKN 
See Lev Nnne Rey pane) PRAVATEREY? | IKN PRIKEY 
[CCIPHERUNIT( number 11)1 CPHRUN 
IDATAKEV FILE Cddname) | DATAKEYVALUE(yajue)! DKFILE DKV 
[SHIPKEYNAMES (keynamel Kevname.+-1)1 SHIPKN 
[STOREDATAKEY | NOSTOREDATAKEY1 STRDK NSTRDK 
[STOREKEYNAME (keyname)1 STRKN 
[USERDATA(yalue)1)1 UDATA 
[FROMKEY (key) | FROMADDRESS (address) | FKEY FADDR 
PROMNUMBER Cnumber } | SKIP (count) 4 FNUM — 
TREPLACE |NOREPLACEI REP NREP 
~ CREUSE | NOREUSE] RUS NRUS 
 [ETOKEY( key) | TOADDRESSladdress) | ——- TADDR 
TONUMBER( number ) [COUNT (count)] TNUM -—~ 





Notes: The ENCIPHER and DECIPHER parameters apply only with the 
Programmed Cryptographic Facility (€5740-XY5) or the IBM 
Cryptographic Unit Support ae XY6). CFor more information, 
see VSAM Administration Guide 
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Parameters 


RESETCAT RCAT 
CATALOG(catnamel/password]I ddname CAT 
eeher treet (ddnanelt ALL| NONE]) a as oe 


CRAVOL 


ddnamel ALL] NONE])...1)] 
CRAVOLUMES((volser[ d ] 
[(volserl devtypel)...1)} 
[IGNORE | NOIGNORE] IGN NIGN 
[MASTERPW( password) ] MRPW 
[WORKCAT (catnamel /password])]1 WCAT 
[WORKFILE(ddnamel/password])] WFILE 


‘Parameters 


{FILE(ddnamel /password] ) | 
DATASET Centrynamel/password] )} 
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EXECUTION CONTROL COMMANDS 


IF-THEN-ELSE COMMAND SEQUENCE 


Parameters 


IF 
{LASTCC|MAXCC} comparand number 
THENE command] 


END) 
Perse command | 


command set 
END]] | 





PARM COMMAND 


PARM 
[TEST ( 
{L{ITRACE] 
EFAREAS(areaidt areaid...1J])] 


CFULL(Cdumpid£l countll€ count2]!1) 
E(dumpid. ++ J++. 107 


OFF} )] 
[GRAPHICS(CHAIN( chain) | TABLE(mname))] 
[MARGINS(leftmargin rightmargin)] 





SET COMMAND 


SET 
{MAXCC|LASTCC} = number | fd 








342 MVS/XA VSAM Catalog: Access Method Services Reference 














The following terms are defined as they 
are used in this book. If you do not 
find the term you are looking for, see 
the index or the ictj 

Computing, SC20-1699. 


access method services. A multifunction 
service program that defines VSAM data 
sets and allocates space for them, 
converts indexed-sequential data sets to 
key~sequenced data sets with indexes, 
modifies data-set attributes in the 
catalog, reorganizes data sets; 
facilitates data portability between 
operating systems, creates backup copies 
of data sets and indexes, helps make 
inaccessible data sets accessible, and 
lists the records of data sets and 
catalogs. 


alias. An alternative name for an 
entry. | 

alias entry. An entry that relates an 
alias Calternate entryname) to the real 
entry name of a user catalog or non-VSAM 
data set. 


alternate-index entry. A catalog entry 
that contains information about an 
alternate index. An alternate index is 
conceptually a Key~sequenced cluster, 
and is cataloged in the same way. An 
alternate-index entry points to a data 
entry and an index entry to describe the 
alternate~index's components, and to a 
cluster entry to identify the 
alternate-index's base cluster. (See 
also cluster entry.) 


alternate-index record. A collection of 
items used to sequence and locate one or 
more data records ina base cluster. 
Each alternate-index record contains an 
alternate-Kkey value and one or more 
pointers. When the alternate index 
supports a key-sequenced data set, each 
data record's prime key value is the 
pointer. When the alternate index 
supports an entry-~sequenced data set, 
the data record's RBA value is the 
pointer. alternate-index 
AES alternate key, base cluster, and 
ey. 


alternate key. One or more characters 
within a data record, used to identify 
the data record or control its use. 
Unlike the prime key, the alternate key 
can identify more than one data record. 
¢ key and key field.) 


application. As used in this 
publication, the use to which an access 
method is put or the end result that it 
serves; contrasted to the internal 
operation of the access method. 





cain alaea detail al aites eaaamertenetetad antares 











backup data set. A copy that can be 
used to replace or reconstruct a damaged 
data set. 


base cluster. The VSAM cluster whose 
data records are to be accessed through 
a path. Usually, a base cluster is the 
key~sequenced or entry~sequenced data 
set which an alternate index supports 
(that is, an alternate index is used by 
VSAM to sequence and locate the data 
records of a base cluster). ( 
alternate-index entry and path. ) 


catalog. 
catalog.) 


(See master catalog and user 


catalog cleanup. A process that allows 
the deletion of entries if their volume 
is no longer available; catalog cleanup 
also allows deletion of a catalog even 
though it is not empty. Catalog cleanup 
is a function of the DELETE command. 


catalog connector. A catalog entry, 
called either a user catalog entry or a 
catalog connector entry, in the master 
catalog that points to a user catalog's 
volume (that is, it contains the volume 
serial number of the direct-access 
volume that contains the user catalog). 


catalog recovery area. An 
entry-sequenced data set that exists on 
each volume owned by a recoverable 
catalog, including the volume on which 
the catalog resides. The CRA contains 
copies of the catalog's records, and can 
be used to recover a damaged catalog. 


cell. An occurrence of information such 
as passwords, volume information, or 
associations. 


cluster. <A data component and an index 
component when data is key sequenced; a 
data component alone when data is entry 
sequenced. 


cluster entry. <A catalog entry that 
contains information about a 
key-sequenced or entry-sequenced VSAM 
cluster: ownership, cluster attributes, 
and the cluster's passwords and 
protection attributes. A key-sequenced 
cluster entry points to a data entry and 
an index entry. An entry-sequenced 
cluster entry points to a data entry. 


component. The data portion or, for a 
key~sequenced cluster, alternate index, 
or VSAM catalog, the index portion of a 
VSAM object. In this book, the 
components of an object are usually 
referred to as the object's data 
component and index component. Also, 
the cluster, data, or index fields of a 
subrecord. 
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control area. <A group of control 
intervals used as a unit for formatting 
a data set before adding records to it. 
Also, in a key~sequenced data set, the 
set of control intervals pointed to by a 
sequence-set index record; used by VSAM 
for distributing free space and for 
placing a sequence~set index record 
adjacent to its data. 


control interval. A fixed-length area 
of auxiliary-~storage space in which VSAM 
stores records and distributes free 
space. It is the unit of information 
transmitted to or from auxiliary storage 
by VSAM 

CRA. (See catalog recovery area.) 

data component. That part of a VSAM 
data set, alternate index, or catalog 
that contains the object's data records. 


data entry. A catalog entry that 
describes the data component of a 
cluster, alternate index, page spaces, 
or catalog. A data entry contains the 
data component's attributes, allocation 
and extent information, and statistics. 
A data entry for a cluster's or 
catalog's data component can also 
contain the data component's passwords 
and protection attributes. 


data integrity. Preservation of data or 
programs for their intended purpose. As 
used in this publication, the safety of 
data from inadvertent destruction or 
alteration. 


data record. <A collection of items of 
information from the standpoint of its 
use in an application, as a user 
supplies it to VSAM for storage. 


data security. Prevention of access to 
or use of data or programs without 
authorization. As used in this 
publication, the safety of data from 
unauthorized use, theft, or purposeful 
destruction. 


data set. The major unit of data 
storage and retrieval in the operating 
system, consisting of data ina 
prescribed arrangement and described by 
control information to which the system 
has access. As used in this 
publication, a collection of fixed- or 
Variable-length records in auxiliary 
storage, arranged by VSAM in key 
sequence or in entry sequence. (See 
key-~sequenced data set and 
entry-sequenced data set.) 


data set control block. A data set 
label for a data set in direct access 
storage. 


data space. A storage area defined in 
the volume table of contents of a 
direct-access volume for the exclusive 


use of VSAM to store data sets, indexes, 
and catalogs. 


direct access. The retrieval or storage 
of data by a reference to its location 
in a data set rather than relative to 
the previously retrieved or stored data. 
(See also addressed direct access and 
keyed direct access.) 


DSCB. (See data set control block.) 


dynamic allocation. The allocation of a 
data set or volume by the use of the 
data set name or volume serial number 
rather than by the use of information 
contained ina JCL statement. 


entry. A collection of information 
about a cataloged object in a VSAM 
master or user catalog. Each entry 
resides in one or more 51l2-byte record. 


entry name. A unique name for each 
component or object as it is identified 
in a catalog. The entryname is the same 
as the dsname in a DD statement that 
describes the object. 


entry sequence. The order in which data 
recerds are physically arranged 
Caccording to ascending RBA) in 
auxiliary storage, without respect to 
their contents. (Contrast with key.) 


entry-sequenced data set. A data set 
whose records are loaded without respect 
to their contents, and whose RBAsS cannot 
change. Records are retrieved and 
stored by addressed access, and new 
es are added at the end of the data 
set. 


esoteric name. An arbitrary name 
provided by the user to identify a group 
of devices having similar 
characteristics (for example, DISK, 
TAPE, SYSDA). 


extent. A continuous space allocated on 
a direct-access storage volume, reserved 
for a particular data space or data set. 
An extent of a data set contains a whole 
number of control areas. 


field. In a record or a control block, 
a specified area used for a particular 
category of data or control information. 


GDG. (See generation data group base 
entry.) 
GDS. (See generation data set.) 


generation data group base entry. An 
entry that permits non-VSAM data sets to 
be associated with other non-VSAM data 
sets as generation data sets. 


generation data set. One of a 
collection of historically related 
non-VSAM data sets; the collection of 
these data sets is Known as a generation 
data group. 
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index. As used in this publication, an 
ordered collection of pairs, each 
consisting of a key and a pointer, used 
by VSAM to sequence and locate the 
records of a key~sequenced data set; 
dn pas in levels of index records. 
(See also index level, index set, and 
sequence set.) 


index component. That part of a 
key~sequenced data set, catalog, or 
alternate index, that establishes the 
sequence of the data records within the 
object it indexes. The index is used to 
locate each record in the object's data 
ones based on the record's key 
value. 


index entry. A catalog entry that 
describes the index component of a 
key-sequenced cluster, alternate index, 
or catalog. An index entry contains the 
index component's attributes, passwords 
and protection attributes, allocation 
and extent information, and statistics. 


index level. <A set of index records 
that order and give the location of 
records in the next lower level or of 
control intervals in the data set that 
1t controls. 


index record. A collection of index 
entries that are retrieved and stored as 
a group. (Contrast with data record.) 


index set. The set of index levels 
above the sequence set. The index set 
and the sequence set together comprise 
the index. 
integrity. (See data integrity.) 

key. One or more characters within an 
item of data that are used to identify 
it or control its use. As used in this 
publication, one or more consecutive 
characters taken from a data record, 
used to identify the record and 
establish its order with respect to 
other records. 


key~sequenced data set. A data set 
whose records are loaded in key sequence 
and controlled by an index. Records are 
retrieved and stored by Keyed access or 
by addressed access, and new records are 
inserted in the data set in Key sequence 
by means of distributed free space. 
Relative byte addresses of records can 
change. 


master catalog. A key-sequenced data 
set with an index containing extensive 
data-set and volume information that 
VSAM requires to locate data sets, to 
allocate and deallocate storage space, 
to verify the authorization of a program 
or operator to gain access to a data 
set, and to accumulate usage statistics 
for data sets. 


non-VSAM entry. A catalog entry that 
describes a non-VSAM data set. A 





non-VSAM entry contains the data set's 
volume serial number and device type. 

If the data set resides on a magnetic 
tape volume, the entry can also identify 
the data set's file number. When the 
data set resides on a direct-access 
device, the operating system obtains 
further information by examining the 
data set's DSCB (data set control block) 
in the volume's VTOC Cvolume table of 
contents). 


object. A logical entity created by 
VSAM, such as a cluster CVSAM data set) 
and its components, an alternate index 
and its components, a VSAM catalog and 
its components, a path, or a VSAM data 
space. 


page space. A VS2 system data set. A 
page space is cataloged as an 
entry~sequenced cluster (that is, the 
page space entry is similar to a cluster 
entry, and it points to a data entry). 


password. A unique string of characters 
stored ina catalog that a program or a 
computer operator at the console must 
supply to meet security requirements 
before the program gains access to a 
data set. 


path. <A data set name for the 
combination of an alternate index and 
its base cluster, or an alias for a VSAM 
data set. 


path entry. A catalog entry that 
contains information about a path, and 
that points to the path's related 
objects. 


plaintext. <A data set or key which is 

not enciphered Cwith the cryptographic 

option). A data set or key is plaintext 
before it is enciphered and after it is 
deciphered. 


portability. The ability to use VSAM 
data sets with different operating 
systems. Volumes whose data sets are 
cataloged ina user catalog can be 
demounted from storage devices of one 
system, moved to another system, and 
mounted on storage devices of that 
system. Individual data sets can be 
transported between operating systems 
using access method services. 


primary space allocation. Initially 
allocated space on a direct-access 
storage device, occupied by or reserved 
for a particular data set. 

secondary space allocation.) 


The index component of a 


(See also index 


prime index. 
key~sequenced data set. 
and alternate index.) 


(See key.) 


qualified name. A name that is 
segmented by periods; each name segment 
is referred to as a qualifier. 


prime key. 


Glossary 345 





RBA. (See relative byte address.) 


record. (See index record, data record, 
stored record.) | 


recoverable catalog. A catalog defined 
with the recoverable attribute. 
Duplicate catalog entries are put into 


CRAs that can be used to recover data in 


the event of catalog failure. 
CRA.3} 


recovery volume. The first volume of a 
prime index, if the VSAM data set is a 
key~sequenced cluster; otherwise, the 
first volume of the data set, if 
entry-sequenced. 


relative byte address. The displacement 
of a data record or a control interval 
from the beginning of the data set to 
which it belongs; independent of the 
manner in which the data set is stored. 


secondary space allocation. A 
contiguous space on a direct-access 
device, occupied by or reserved for a 
particular data set, which is allocated 
after space in the primary extent has 
been exhausted. ( primary space 
allocation.) 


(See data security.) 


sequence set. The lowest level of the 
index of a key~sequenced data set; it 
gives the locations of the control 
intervals in the data set and orders 
them by the key sequence of the data 
records they contain. The sequence set 
ae the index set together comprise the 
index. 


security. 


spanned record. A logical record whose 
length exceeds control interval length, 
and crosses (Cor spans) one or more 


control interval boundaries within a 
control area. 


sphere record. A collection of 
logically related subrecords in one VSAM 
logical record. 
step catalog. (See job catalog.) 
stored record. A data record, together 
with its control information, as stored 
in auxiliary storage. 


subrecord. The user definition level of 
a sphere, such as an AIX, cluster, or 
generation data set. 


user catalog. A catalog used in the 
same way as the master catalog, but 
optional and pointed to by the master 
catalog, and also used to lessen the 
contention for the master catalog and to 
facilitate volume portability. 


user catalog connector. (See catalog 
connector.) Interval in the data set 
controlled by the index. 


volume cleanup. The process of deleting 
all VSAM data spaces from a volume and 
removing a VSAM catalog's ownership of 
the volume, even though the volume 
contains VSAM data records. 


volume entry. A catalog entry that 
describes a volume owned by the catalog. 
All VSAM data spaces on the volume are 
described in the volume entry, and the 
catalog is no longer available. 


volume table of contents. A table ona 
direct access volume that describes each 
data set on the volume. 


VTOC. (See volume table of contents.) 
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abbreviations 
TSO restrictions 13 
abort a job 10 
access 
read only 
in EXPORT command 175 
access method services 
coding commands 3 
continuing commands 7 
parameters 
password 5 
structure 3 
subparameters 4, 5 
function 
functional commands 29 
summary 1, 326 
invoking 
TSO terminal 13 
ADDVOLUMES parameter 
in ALTER command 34 
ALIAS parameter 
in DEFINE command 60 
in DELETE command 154 
in LISTCAT command 206 
aliasname subparameter 
coding 
ALL parameter 
in LISTCAT command 210 
output listing 284 
ALL subparameter 
in EXPORTRA 180 
in RESETCAT command 247 
ALLOCATION parameter 
in LISTCAT command 210 
output listing 292 
allocation, space 
direct ll 
dynamic 8 
JCL DD statement 9 
alphabetic characters 6 
alphameric characters 6 
ALTER command 
entry types that can be altered 31 
examples 47 
format 31 
order of catalog search 15 
parameters 
optional 34 
required 34 
alternate index 
building (BLDINDEX) 49 
creating 
example 83 
defining 64 
deleting 154 
exporting 174 
importing 189 
path 130 
record size 75 
alternate key 73 
alternate name 
deleting 154% 
alternate target data set 
identification 











JCL DD statement 10 
ee eae parameter 
n DELETE command 154 
ah LISTCAT command 206 
ALTERNATEINDEX subcommand 
in DEFINE command 64 
AMSDUMP DD statement 10 
APF Cauthorized program facility) 
authorization 9 
AREAS parameter 
in PARM command 24 
argument lists 
referenced by invoking macros 319 
ATTACH macro 14, 319 
ATTEMPTS parameter 
in ALTER command 34 
in DEFINE command 
ALTERNATEINDEX 67 
CLUSTER 990 
PAGESPACE 123 
PATH 131 
USERCATALOG 142 
note to TSO users 35 
attributes 
nullifying 39 
AUTHORIZATION parameter 
in ALTER command 35 
NULLIFY 40 
in DEFINE command 
ALTERNATEINDEX 67 
CLUSTER 90 
PAGESPACE 124 
PATH 131 
USERCATALOG 142 
authorized program facility 
See APF 
Auxiliary Storage Management 126 


BIND parameter 
in ALTER command 44 
in DEFINE command 
ALTERNATEINDEX 79 
ee 104 
bindin 
MSS. (Mass Storage System) 20 
blanks 
separators 3 
BLDINDEX command 
example 52 
format 49 
order of catalog selection 15 
parameters 
optional 50 
required 49 
buffer 
altering size 35 
buffering 
VSAM data sets 9 
BUFFERSPACE parameter 
in ALTER command 35 
in DEFINE command 
ALTERNATEINDEX 67 
CLUSTER 90 
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USERCATALOG 142 
building an alternate index 49 


[Le | 


CALL macro 14, 320 
CANDIDATE parameter 
in DEFINE command 
SPACE 136 
CATALOG parameter 
in ALTER command 35 
in BLDINDEX command 50 
in CNVTCAT command 57 
in DEFINE command 
ALIAS 60 
ALTERNATEINDEX 68 
CLUSTER 91 
GENERATIONDATAGROUP 114 
NONVSAM 119 
PAGESPACE 123 
PATH 131 
SPACE 138 
USERCATALOG 142 
in DELETE command 156 
in IMPORT command 191 
in IMPORT CONNECT command 186 
ain IMPORTRA command 199 
in LISTCAT command 207 
in LISTCRA command 213 
in RESETCAT command 247 
catalog recovery 
example 203 
catalog recovery space 144 
catalogs 
connecting to master catalog 
in IMPORT command 186 
defining 140 
deleting entries 154 
listing entries 205 
CHAIN parameter 
in PARM command 25 
maleic parameter 
n PRINT command 218 
CHECKID parameter 
in CHKLIST command 53 
checkpoint data set 53 
CHKLIST command 
examples 55 
format 53 
listing tape volumes mounted at 
checkpoint 53 
parameters 
optional 53 
required 53 
sample output 315 
CIPHERUNIT parameter 
in REPRO command 
ENCIPHER 231 
cluster 
creating 87 
defining 87 
deleting 154 
exporting 174 
importing 189 
listing its catalog entry 206 
path 130 
printing its contents 217 


verifying its end-of-file values 254 


CLUSTER parameter 
in DELETE command 154 
in LISTCAT command 206 


CLUSTER subcommand 
in DEFINE command 87 
CNVTCAT command 
examples 58 
format 56 
order of catalog selection 16 
parameters 
optional 57 
required 56 
CODE parameter 
in ALTER command 36 
NULLIFY 40 
in DEFINE command 
ALTERNATEINDEX 68 
CLUSTER 91 
PAGESPACE 124 
PATH 132 
USERCATALOG 143 
CODE subparameter 
coding 
coding 


access method services commands 3 


aliasname subparameter 
alphameric characters 6 
CODE subparameter 5 
continuing commands 4, 7 
control commands 
continuation errors 26 
entryname subparameter 5 
entrypoint subparameter 6 
keyword parameter 3 
national characters 6 
NEWNAME subparameter 6 
ownerid subparameter 6 
parameters 
parentheses 4 
password 5 
PASSWORD subparameter 6 


pdsname(membername) subparameter 


positional parameter 

special character 5, 6 

string subparameter 6 

subparameters 

terminator 8 

volser subparameter 

command execution, controlling 21 
commands, access method services 

ALTER 31 

BLDINDEX 49 

CHKLIST 53 

CNVTCAT 56 

DEFINE 
ALIAS 60 
ALTERNATEINDEX 62 
CLUSTER 85 
GENERATIONDATAGROUP 114 
MASTERCATALOG 140 
NONVSAM 118 
PAGESPACE 122 
PATH 130 
SPACE 136 
USERCATALOG 140 

DELETE 153 

EXPORT 174 

EXPORT DISCONNECT 172 

EXPORTRA 179 

IMPORT 189 

IMPORT CONNECT 186 

IMPORTRA 199 

LISTCAT 205 

LISTCRA 213 

PRINT 217 

REPRO 226 

RESETCAT 247 
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summary 1, 326 


VERIFY 254 
commas 

separators 3 
comments 

coding 3 


COMPARE parameter 
in LISTCRA command 213, 214% 
LISTCRA command 
output listing 312 
components 
in DEFINE command 
USERCATALOG 146 
concatenated DD statement 
defining a cluster 93 
FILE parameter 37 
condition codes 21 
controlling command execution 2] 
processor 
CONNECT subcommand 
in IMPORT command 186 


connecting a user catalog 


in IMPORT command 186 
continuation mark 
hyphen 7 
plus sign 4 
continuing commands 
coding 
control area 
preformatting 
alternate index 78 
cluster 103 
control commands 
continuation errors 26 
control interval 
crossing boundaries 102 
Cole volume pointer entry 
ee 
CONTROLINTERVALSIZE parameter 
in DEFINE command 
ALTERNATEINDEX 68 
CLUSTER 91 
controlling command execution 2] 
condition codes 
examples 27 
null commands 23 
CONTROLPW parameter 
in ALTER command 36 
NULLIFY 40 
in DEFINE command 
ALTERNATEINDEX 69 
CLUSTER 92 
PAGESPACE 124 
PATH 132 
USERCATALOG 143 
converting a catalog 56 
copying 
a data set 226 
a SAM data set 227 
catalog 
examples 236 
ISAM records 227 
copying catalogs for device conversion, 
example 
COUNT parameter 
in PRINT command 221 
in REPRO command 231 
CRA parameter 
in EXPORTRA command 179 
CRAFILES parameter 
in RESETCAT command 247 
CRAVOLUMES parameter 
in RESETCAT command 247 
CREATION parameter 
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in LISTCAT command 207 
output listing 297 
cross~region sharing 
alternate index 76 
in ALTER command 42 | 
in DEFINE CLUSTER command 100 
cross-system sharing 
alternate index 77 
in ALTER command 43 
in DEFINE CLUSTER 101 
cryptographic option 
access method services 
parameters 
examples 242, 246 
CVOLEQUATES parameter 
in CNVTCAT command 57 
CVPE (control volume pointer entry) 
CYLINDERFAULT parameter 
in ALTER command 44% 
in DEFINE command 
ALTERNATEINDEX 79 
CLUSTER 104 
CYLINDERS parameter 
in DEFINE command 
ALTERNATEINDEX 64 
CLUSTER 87 
PAGESPACE 122 
SPACE 137 
USERCATALOG 141 


[> | 


data component 
alternate index 63, 82 
cluster 86, 105 
control interval size 9] 
record size 
user catalog 146 
data encrypting Key 
cryptographic option 231 
establishing 2 
data integrity 
sharing data sets 
cluster 100 
in DEFINE ALTERNATEINDEX 
command 76 
data organization 
specifying 95 
DATA parameter 
in LISTFCAT command 206. 
data set 
creating 87 
defining 
example 106 
identification 8 
organization 95 
protection 9 
sharing 
cluster 100 
in ALTER command 
in DEFINE AL TERNATEINDEX 
command 76 
unique 80, 104 
data set type 
specifying 95 
data space 
allocating 136 
defining 1536 
examples 139 
extending 137 
recovery area 122 
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suballocation 
alternate index 80 
DATAKEYFILE parameter 
in REPRO command 
DECIPHER 234% 
ENCIPHER 232 
DATAKEYVALUE parameter 
in REPRO command 
DECIPHER 234 
ENCIPHER 232 
DATASET parameter 
in VERIFY command 254 
DATATEST parameter 
in EXAMINE command 170 
debugging tool 
TRACE 24 
DECIPHER parameter 
in REPRO 
examples 244 
in REPRO command 234 
DEFINE command 
ALIAS 
examples 61 
format 60 
optional parameter 60 
required parameters 60 
ALTERNATEINDEX 
data component 63 
example 
format 62 
index component 63 
optional parameter 67 
required parameters 64 
CLUSTER 
data component 86 
data organization 95 
example 
format 85 
index component 86 
optional parameters 90 
required parameters 87 
GENERATIONDATAGROUP 
format 114 
optional parameters 114 
required parameters 114 
MASTERCATALOG | 
required parameters 140 
NONVSAM 
format 118 
optional parameters 119 
required parameters 118 
order of catalog selection 
PAGESPACE 
examples 128 
format 122 
optional parameters 123 
required parameters 122 
PATH 
examples 135 
format 130 
optional parameters 131 
required parameters 130 
SPACE 
examples 139 
format 136 
optional parameters 138 
required parameters 136 
USERCATALOG 
components 146 
example 1947 
format 1450 
optional parameters 142 
required parameters 140 
defining a cluster 85 


16 


defining a data space 136 
defining a 
defining a non-VSAM data set 
defining a page space 122 
defining a path 130 
defining a user catalog 140 
example 147 | 
defining an alias 60 
defining an alternate entryname 
defining an alternate index 62 
alternate index 62 
DELETE command 
catalog cleanup 164 
example 161 
format 153 
optional parameters 154 
order of catalog search 17 
required parameters 153 
deleting 
catalog entries 154 
examples 161 
delimiter 
in PRINT command 219 
in REPRO command 227, 230 
DESTAGEWAIT parameter 
in ALTER command 36 
in DEFINE command 
ALTERNATEINDEX 69 
CLUSTER 92 
USERCATALOG 143 
destaging 36 
MSS (Mass Storage System) 19 
DEVICETYPES parameter 
in DEFINE command 
NONVSAM 118 
in IMPGRT CONNECT command 186 
in IMPORTRA command 200 
direct allocation 11 
DISCONNECT subcommand 
in EXPORT command 172 
disconnecting a user catalog 
an EXPORT command 
DO command 21, 23 
DO-END command sequence 21, 23 
dummy records 
copying 227 
DUMP COMPARE output listing 
LISTCRA command 3 
DUMP output listing 
LISTCRA command 308 
DUMP parameter 
in LISTCRA command 214 
in PRINT command 218 
dynamic allocation 8 


Le | 


aaa Rs alae 21 
IF command 23 _ 
EMPTY parameter 
in ALTER command 36. 
in DEFINE command 
GENERATIONDATAGROUP 115 
ENCIPHER parameter 
in REPRO command 231 
examples 242 
END command 21, 23 
ENTRIES parameter 
in EXPORTRA command 180 
in LISTCAT command 208 
entry~sequenced data set 95 
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defining 
example 110 
exporting 
example 178 
importing 
example 198 
entryname subparameter 
coding 5 
entrypoint subparameter 
coding 
Ee onean. parameter 
REPRO command 227 
ERASE parameter 
in ALTER command 37 
in DEFINE command 
ALTERNATEINDEX 70 
CLUSTER 93 
in DELETE command 157 
- EXPORT command 175 
IMPORT command 191 
ERRORLIMIT parameter 
in EXAMINE command 170 
esoteric name 
EXAMINE command 
format 169 
optional parameters 170 
required parameters 169 
examples 
controlling command execution 27 
exception 
I/O error 37 
EXCEPTIONEXIT parameter 
in ALTER command 37 
in ALTER command (CNULLIFY) 40 
in DEFINE command 
ALTERNATEINDEX 70 
CLUSTER 93 
EXEC statement 12 
EXPIRATION parameter 
in LISTCAT command 209 
output listing 297 
EXPORT command 
examples 177 
format 174 
ide late parameters 175 
quired parameters 174 
EXPORT DISCONNECT command 
example 173 


format 172 
required parameters 172 
exporting 


VSAM recoverable catalogs 179 
EXPORTRA command 

examples 182 

format 179 

optional parameters 1381 

required parameters 179 
external file key 

cryptographic option 231 
EXTERNALKEYNAME parameter 

in REPRO command 

ENCIPHER 231 

EXTERNALSORT parameter 

in BLDINDEX command 51 








FILE parameter 
in ALTER command 37 
in DEFINE command 
ALTERNATEINDEX 70 
CLUSTER 93 
PAGESPACE 124 
PATH 132 
SPACE 138 
USERCATALOG 143 
in DELETE command 157 
in IMPORT command 192 
in IMPORTRA command 201 
in VERIFY command G 
FILESEQUENCENUMBERS parameter 
in DEFINE command 
NONVSAM 120 
fixed-length records 99 
FOR parameter 
in ALTER command 44 
in DEFINE command 
ALTERNATEINDEX 79 
CLUSTER 104 
GENERATIQNDATAGROUP 116 
NONVSAM 120 
PAGESPACE 126 
PATH 133 
USERCATALOG 145 
FORCE parameter 
in DELETE command 158 
in EXPORTRA command 18] 
FREESPACE parameter 
in ALTER command 37 
in DEFINE command 
ALTERNATEINDEX 71 
CLUSTER 94 
FROMADDRESS parameter 
in PRINT command 219 
in REPRO command 228 
FROMKEY parameter 
in PRINT command 219 
in REPRO command 228 
FROMNUMBER parameter 
in PRINT command 220 
in REPRO command 228 
FULL parameter 
in PARM command 25 
functional commands 
summary 1, 29 
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generation data group 
altering attributes 
example 
creating 114 
defining 
example 116 
generation data set 
cataloging maximum number 36 
uncataloging 42 
ad ea Nee a parameter 
n DELETE command 55 
LISTCAT command 206 
GENERATIONDATAGROUP subcommand 
nm DEFINE command 114 
senarie key 
specified in PRINT command 219 
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generic name 
altering 
example 47 
device type 118 
global resource serialization 
See GRS 
glossary 343 
GRAPHICS parameter 
in PARM command 25 
GRS Cglobal resource serialization) 
multiple system sharing 42, 76, 101 
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HEX parameter 
in PRINT command 218 
high key 
alternate index 72 
cluster 
HISTORY parameter 
in LISTCAT command 209 
output listing 295 
hyphen 
continuation mark 7 
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I/0 routines 
user controlled 323 
IDCAMS program 12, 321 
identifying tape volumes 
CHKLST command 
IF command 21, 
IF-THEN-ELSE command sequence 21, 22 
null commands 
IGNORE parameter 
in RESETCAT command 248 
IMBED parameter 
in DEFINE command 
ALTERNATEINDEX 71 
CLUSTER 94 
IMPORT command 
format 189 
optional parameters 191 
required parameters 189 
IMPORT CONNECT command 
example 
format 186 
optional parameters 186 
required parameters 186 
importing recoverable catalogs 199 
IMPORTRA command 
format 199 
optional parameters 199 
required parameters 199 
INDATASET parameter 
in BLDINDEX command 49 
in IMPORT command 189 
in IMPORTRA command 199 
in PRINT command 217 
in REPRO command 226 
index component 
alternate index 63, 82 
cluster 86, 105 
key~sequenced cluster 
control interval size 92 
user catalog 146 
INDEX parameter 


in LISTCAT command 206 
INDEXED parameter 
in DEFINE command 
CLUSTER 95 
INDEXTEST parameter 
in EXAMINE command 169 
INFILE parameter 
in BLDINDEX command 49 
in CHKLIST command 53 
in CNVTCAT command 56 
in EXPORT command 175 
in EXPORTRA command 180 
in IMPORT command 9 
in IMPORTRA command 199 
in LISTCRA command 213 
2 PRINT command 217 
n REPRO command 226 
INHIBIT parameter 
in ALTER command 38 
INHIBITSOURCE parameter 
in EXPORT command 175 
INHIBITTARGET parameter 
in EXPORT command 176 
internal file key 
cryptographic option 231 
INTERNALKEYNAME parameter 
in REPRO command 
ENCIPHER 231 
INTERNALSORT parameter 
in BLDINDEX command 51 
INTOEMPTY parameter 
in IMPORT command 192 
invoking access method services 12 
from problem program 319 
PL/I program 
invoking macro instructions 319 





JCL Cjo0b control language) 
for LISTCAT jobs 276 
for LISTCRA jobs 303 
JCL DD parameter 
cautions 316 
JCL DD statement 9 
invoking access method services 12 
JOB statement 12 
JOBCAT DD statement 12 
allocating user catalogs ll 
key 
cryptographic option 231 
key field 
alternate index 73 
key sequenced data set 
defining 
example 108, 111 
key value 
alternate index 80 
key-~sequenced data set 95 
exporting 
example 177 a 
importing | | (fs 
example 197 ‘ae Y 


KEYRANGES parameter 
in DEFINE command 


352 MVS/XA VSAM Catalog: Access Method Services Reference 


























ALTERNATEINDEX 72 
CLUSTER 96 
in IMPORT command 192 
KEYS parameter 
in ALTER command 38 
in DEFINE command 
ALTERNATEINDEX 73 
CLUSTER 97 
keyword parameter 
coding 
keywords 
LISTCAT output 256 


LASTCC condition code 
using 323 
LASTCC parameter 
in IF command 22 
in SET command 24 
length 
alternate Key 73 
LEVEL parameter 
in LISTCAT command 208 
LIMIT parameter 
in DEFINE command 
GENERATIONDATAGROUP 114 
LINK macro 14, 319 
LIST parameter 
in CNYTCAT command 57 
LISTCAT command 
examples 211 
format 205 
in TSO environment 
examples 299 
interpreting listings 256 
optional parameters 205 
order of catalog search 18 
output keywords 256 
LISTCRA command 
format 213 
interpreting listings 301 
optional parameters 213 
required parameters 213 
listing catalog entries 205 
listing recoverable catalogs 213 
LOAD macro 14, 320 


low key 
alternate index 72 
cluster 96 
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cros 
ATTACH 319 
CALL 320 
LINK 319 
LOAD 320 
margins 
coding 3 
MARGINS parameter 
in PARM command 25 
Mass Storage System 


See MS 
MASTERCATALOG parameter 
in CNVTCAT command 58 
MASTERCATALOG subcommand 
in DEFINE command 140 
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MASTERPW parameter 
in ALTER command 39 
NULLIFY 40 
in DEFINE command 
ALTERNATEINDEX 73 
CLUSTER 97 
PAGESPACE 125 
PATH 132 
USERCATALOG 143 
in EXPORTRA command 181 
in LISTCRA command 214 
in RESETCAT command 248 
MAXCC parameter 
in IF command 22 
in SET command 24 
maximum condition code 22 
modal command 
PARM command 26 
TSO restrictions 14 
model 
using to define cluster 
example 112 
MODEL parameter 
example 150 
in DEFINE command 
ALTERNATEINDEX 73 
CLUSTER 97 
PAGESPACE 125 
PATH 132 
USERCATALOG 144 
MODULE parameter 
in ALTER command 
NULLIFY 40 
MSS (Mass Storage System) 
restrictions 1 
multiple system sharing 
GRS (global resource 
serialization) 4%2, 76, 101 
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NAME parameter 
in DEFINE command 
ALIAS 60 
ALTERNATEINDEX 64 
CLUSTER 87 
GENERATIONDATAGROUP 114 
NONVSAM 118 
PAGESPACE 122 
PATH 130 
USERCATALOG 141 
in EXAMINE command 169 
in LISTCAT command 209 
in LISTCRA command 214 
national characters 7 
NEWNAME parameter 
in ALTER command 39 
in IMPORT command 193 
NEWNAME subparameter 
coding 
NOCOMPARE parameter 
in LISTCRA command 214 
NODATATEST parameter 
in EXAMINE command 170 
NODESTAGEWAIT parameter 
ain ALTER command 36 
in DEFINE command 
ALTERNATEINDEX 69 
CLUSTER 93 
USERCATALOG 143 
NOEMPTY parameter 
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in ALTER command 36 

in DEFINE command 

' GENERATIONDATAGROUP 

NOERASE parameter 

in ALTER command 37 

in DEFINE command 
ALTERNATEINDEX 70 
CLUSTER 93 

in DELETE command 157 

in EXPORT command 175 
IMPORT command 19], 


‘NOFORCE parameter 


in BELETE command 159 

in EXPORTRA command 181 
NOIGNORE parameter ee 

in RESETCAT command 248 
NOIMBED parameter 

in DEFINE command 

CLUSTER 94 

NOINDEXTEST parameter 

in EXAMINE command 169 
NOINHIBITSOURCE parameter 

in EXPORT command 175 
NOINHIBITTARGET parameter 

in EXPORT command 176 
NOLIST parameter 

in CNVTCAT command 57 
non-VSAM data set 

creating 118 


defining 
example 121 
identification 


dynamic allocation 8 
JCL DD statement 10 
NONE parameter 
in EXPORTRA command 180 
NONE subparameter 
in RESETCAT command 247 
NONINDEXED parameter 
in DEFINE command 
CLUSTER 95 . 
NONSPANNED parameter 
in DEFINE command 
CLUSTER 103 
nonspanned record 
record size 99 
NONUNTQUEKEY parameter 
in ALTER command 45 
in DEFINE command 
ALTERNATEINDEX 81 
NONVSAM parameter 
in DELETE command 155 
in LISTCAT command 206 
NONVSAM subcommand 
in DEFINE command 118 
NOPURGE parameter 
in DELETE command 159 
in EXPORT command 176 
in IMPORT command 195 
NOREPLACE parameter 
in REPRO command 229 
NOREPLICATE parameter 
in DEFINE command 
ALTERNATEINDEX 76 
CLUSTER 100 
NOREUSE parameter 
in DEFINE command 
ALTERNATEINDEX 76 
CLUSTER 100 
in REPRO command 230 
NOSAVRAC parameter 
in IMPORT command 196 
in IMPORTRA command 202 
NOSCRATCH parameter 
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in ALTER command 42 
in DEFINE command 


GENERATIONDATAGROUP 115 


in DELETE command 159 
NOSTOREDATAKEY parameter 
in REPRO command 
ENCIPHER 233 
NOSWAP parameter 
in DEFINE command 
PAGESPACE 126 
NOTRECOVERABLE parameter 
in DEFINE command 
USERCATALOG 145 
NOTUSABLE parameter 
in LISTCAT command 210 
NOUPDATE parameter 
in ALTER command 45 
in DEFINE command 
PATH 134 


NOUPGRADE parameter 


in ALTER command 45 
in DEFINE command 
ALTERNATEINDEX 81 
NOWRITECHECK parameter 
in ALTER command 46 
in DEFINE command 
ALTERNATEINDEX 82 
CLUSTER 105 
USERCATALOG 146 
null commands 23 
NULLIFY parameter 
in ALTER command 39 
NUMBERED parameter 
in DEFINE command 
CLUSTER 95 
numeric characters 6 
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OBJECTS parameter 


in IMPORT CONNECT command 


in IMPORTcommand 192 
in IMPORTRA command 200 
OFF parameter 
in PARM command 25 
offset 
alternate key 73 
order of catalog use 15 
ALTER 15 
BLDINDEX 15 
CNVTCAT 16 
DEFINE 16 
DELETE 17 
LISTCAT 18 
ORDERED parameter 
in DEFINE. command 
ALTERNATEINDEX 74 
CLUSTER 98 
in IMPORT command 193 
OS CVOL 


converting to VSAM catalog 56 


example 58, 59 

OUTDATASET parameter 

in BLDINDEX command 50. 

in CNVTCAT command 57 

in EXPORT command 174 

in IMPORT command 190 

in REPRO command 227 
OUTFILE parameter 

in BLDINDEX command 50 

in CHKLIST command 54 
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in CNVTCAT command 56 
in EXPORT command 174 
in EXPORTRA command 179 
in IMPORT command 190 
in IMPORTRA command 201 
in LISTCAT command 210 
in LISTCRA command 215 
in PRINT command 220 
in REPRO command 227 
output keywords 
LISTCAT command 256 
output listing 
LISTCAT command 256 
LISTCRA 301 
OWNER parameter 
in ALTER command 41 
NULLIFY 40 
in DEFINE command 
ALTERNATEINDEX 74 
CLUSTER 98 
GENERATIONDATAGROUP 115 
NONVSAM 120 
PAGESPACE 125 
PATH 133 
USERCATALOG 144 
ownerid subparameter 
coding 
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page space 

creating 122 
PAGESPACE parameter 

in DELETE command 155 

in LISTCAT command 206 
PAGESPACE subcommand 

in DEFINE command 122 
parameters 

coding 7 
parentheses 

coding 4% 

TSO restrictions 13 
PARM command 21, 24 

modal command 26 
partitioned data set 

renaming 
password subparameter 

coding 5, 

TSO restrictions 14 
path 

creating 130 
PATH parameter 

in DELETE command 155 

in LISTCAT command 206 
PATH subcommand 

in DEFINE command 130 
PATHENTRY parameter 

in DEFINE command 

PATH 130 

pdsname(membername) subparameter 

coding 6 
PERMANENT parameter 

in EXPORT command 176 
PL/I program 

invoking access method services 321 
plus sign 

continuation mark 4 
portable data set 

exporting to 174 

for importing 189 
positional parameter 








coding 3 
preformatting 
control areas 
alternate index 78 
cluster 103 
primary space allocation 
alternate index 65 
cluster 88 
data space 137 
page space 122 
user catalog 141 
prime key field 97 
PRINT command 
format 217 
optional parameters 218 
required parameters 217 
printing 
contents of a data set 217 
private key 
decipher 
example 246 
encipher 
example 245 
PRIVATEKEY parameter 
in REPRO command 
ENCIPHER 231 
problem program 
invoking access method services 319 
using macro instructions 319 
processing program 
invoking access method services 14 
processor condition codes 
processor invocation 323 
argument list 323 
protection attribute 
nullifying 39 
PURGE parameter 
in DELETE command 159 
in EXPORT command 176 
in IMPORT command 195 
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RACF CResource Access Control Facility) 
data set profiles 
READPW parameter 
in ALTER command 41 
NULLIFY 40 
in DEFINE command 
ALTERNATEINDEX 75 


CLUSTER 98 

PAGESPACE 126 

PATH 133 

USERCATALOG 144 
record 
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